02-Backend-Modules

A. Projects

A project represents one real software codebase cloned into an isolated workspace.

Fields

• id

• name

• slug (unique, URL-safe)

• description

• repository_url

• local_workspace_path (absolute path under workspace_root)

• default_branch (e.g. main)

• current_branch

• framework_detected (laravel, nextjs, swift, python, …)

• language_detected (php, ts, swift, python, …)

• status (creating, cloning, indexing, ready, error, archived)

• created_by (FK → users)

• created_at / updated_at

Features

• create project, connect Git repo, clone, pull.

• detect framework / language.

• detect Laravel routes, controllers, models, migrations, services, config files, package files.

• generate PROJECT_MAP.md.

• index project into RAG.

Service: App\Services\Workspace\ProjectService + App\Services\Docs\ProjectMapService + App\Services\Rag\ProjectIndexer.

B. Agent Runs

One coding task = one run.

Fields

• id

• project_id (FK)

• user_id (FK)

• title

• prompt (text)

• status (draft, queued, running, paused, waiting_for_user, completed, failed, cancelled)

• current_step (string, agent-defined)

• selected_agent (architect, backend, frontend, iphone, rag, qa, devops, documentation)

• selected_model (e.g. gpt-4.1, claude-3.7-sonnet, claude-code:default)

• branch_name (agent/run-{id}-{slug})

• started_at / completed_at / failed_reason

• metadata_json (RAG toggle, safe mode, tool config, pause reason, …)

Features: create, start, pause, resume, cancel, retry, timeline, live console, file changes, AI decisions, final summary. Every step is persisted.

Service: AgentRunOrchestrator (state machine) + queued RunAgentJob.

C. Agent Events

Atomic unit of the console log.

Fields

• id

• run_id (FK)

• project_id (FK, denormalized for fast scoping)

• event_type (enum, see below)

• title

• message (short human text)

• payload_json (full structured payload)

• severity (info, success, warning, error, debug)

• created_at

Event types

user_prompt              ai_context_loaded         rag_search_started
rag_search_completed     ai_plan_created           file_read
file_created             file_updated              file_deleted
command_started          command_output            command_failed
command_completed        git_status_checked        git_branch_created
git_diff_created         snapshot_created          docs_updated
test_started             test_completed            test_failed
paused_for_input         resumed                   final_summary

Rules

• Every event is persisted before being broadcast.

• Broadcasting is fire-and-forget on a Redis pubsub channel run:{run_id}:events.

• SSE endpoint replays from DB up to ?since=event_id then tails Redis.

Service: ConsoleEventService::emit(Run $run, EventType $type, array $payload, Severity $sev = Info).

D. Workspace Files

Every file the agent touches.

Fields

• id

• project_id / run_id

• path (relative to project root)

• action (read, create, update, delete)

• before_hash (sha256, nullable)

• after_hash (sha256, nullable)

• diff (unified diff, nullable, may be in S3 for huge files)

• snapshot_id (FK, nullable)

• created_at

Features: show changed files, before/after diff, explanation (linked event), approve/reject (writes to run metadata), restore from snapshot.

E. Snapshots & Revisions

Recoverability primitive.

Fields

• id

• project_id / run_id

• snapshot_type (pre_run, pre_command, manual, final)

• git_commit_hash (nullable — set when the snapshot is also a commit)

• archive_path (nullable — S3 key to a tarball when needed)

• description

• created_at

Rules

• A pre_run snapshot is mandatory if snapshot_before_run server param is true (default true).

• A pre_command snapshot is automatic before any command flagged destructive: true in the command allowlist.

• restore(snapshot_id) checks out the commit and (if archive present) overlays the tarball. Always logs snapshot_restored event.

F. RAG (see dedicated page 04)

G. Agent Providers & Settings

Tables

• agent_providers — registered providers (openai, claude_api, claude_code, local_shell). Static seed.

• agent_settings — key/value, encrypted-at-rest where flagged. Holds API keys, models, toggles. See 08.

H. Git Operations

git_operations fields: id, project_id, run_id, operation (clone, pull, status, branch, commit, push, diff, restore), args_json, result_json, stdout, stderr, exit_code, created_at. Powers the Git audit log.

I. Documentation Updates

documentation_updates fields: id, project_id, run_id, doc_path, change_summary, diff, created_at. Used to render the auto-docs changelog and CHANGELOG_AI.md.

J. Command Executions

command_executions fields: id, project_id, run_id, command, args_json, working_dir, timeout_seconds, started_at, finished_at, exit_code, stdout_path (S3), stderr_path (S3), was_killed, was_blocked, block_reason.

K. Run Reviews

run_reviews fields: id, run_id, reviewer_user_id, decision (approved, rejected, commented), notes, created_at. Captures human approval before push.

L. API Tokens

Sanctum's personal_access_tokens is sufficient. Extend abilities: projects:read, projects:write, runs:start, runs:control, git:push, settings:write.

M. Indexes (must-have)

• agent_events (run_id, id) for fast tail queries.

• agent_events (project_id, created_at).

• workspace_files (run_id) and (project_id, path).

• rag_chunks (project_id, source_type) and (content_hash).

• agent_runs (project_id, status).

• command_executions (run_id, started_at).

N. Entity Relationship Diagram

erDiagram
	USERS ||--o{ PROJECTS : owns
	USERS ||--o{ AGENT_RUNS : creates
	PROJECTS ||--o{ AGENT_RUNS : has
	AGENT_RUNS ||--o{ AGENT_EVENTS : emits
	AGENT_RUNS ||--o{ WORKSPACE_FILES : changes
	AGENT_RUNS ||--o{ WORKSPACE_SNAPSHOTS : produces
	AGENT_RUNS ||--o{ COMMAND_EXECUTIONS : runs
	AGENT_RUNS ||--o{ GIT_OPERATIONS : performs
	AGENT_RUNS ||--o{ DOCUMENTATION_UPDATES : writes
	PROJECTS ||--o{ RAG_CHUNKS : indexed_into
	WORKSPACE_FILES }o--|| WORKSPACE_SNAPSHOTS : references