16-Documentation-Templates

🗺️

Canonical Markdown templates that the Documentation Agent fills in. Mirror these into the codebase as docs/PROJECT_MAP.md, docs/DATABASE_SCHEMA.md, and docs/ARCHITECTURE_DIAGRAMS.md.

1. `docs/PROJECT_MAP.md`

The single central source of truth for how the project is connected.

# Project Map

_Last updated by agent run: <run_id> on <ISO-8601 timestamp>_

## Routes ↔ Controllers ↔ Models ↔ Tables ↔ Services

<!-- AUTO-GENERATED:START -->
| Route | Method | Name | Controller | Action | Model | Table | Service | View / Component | Policy / Middleware | Tests | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| /api/projects | GET | projects.index | ProjectController | index | Project | projects | ProjectService | — | auth:sanctum, ability:projects:read | tests/Feature/ProjectIndexTest.php | List user-accessible projects. |
| /api/projects | POST | projects.store | ProjectController | store | Project | projects | ProjectService | — | auth:sanctum, ability:projects:write | tests/Feature/ProjectStoreTest.php | Clones repo + queues RAG index. |
| /api/runs/{run}/events/stream | GET | runs.events.stream | RunEventStreamController | __invoke | AgentEvent | agent_events | ConsoleEventService | — | auth:sanctum | tests/Feature/RunEventStreamTest.php | SSE; supports Last-Event-ID. |
| … | | | | | | | | | | | |
<!-- AUTO-GENERATED:END -->

## Background jobs

<!-- AUTO-GENERATED:START -->
| Job | Queue | Trigger | Touches |
|---|---|---|---|
| RunAgentJob | agents-long | POST /api/runs/{run}/start | agent_runs, agent_events, workspace_files, workspace_snapshots, git_operations |
| ProjectIndexerJob | rag-index | POST /api/projects/{project}/index-rag, file change events | rag_chunks |
| DocumentationUpdateJob | docs | final_summary event | docs/*, .claude/*, .cursor/rules/*, documentation_updates |
| SnapshotGcJob | docs | scheduled (daily) | workspace_snapshots, S3 archives |
<!-- AUTO-GENERATED:END -->

## Services

<!-- AUTO-GENERATED:START -->
| Service | Owns | Used by |
|---|---|---|
| ProjectService | Project model lifecycle | ProjectController |
| AgentRunOrchestrator | run state machine | RunAgentJob |
| RagContextService | rag_chunks retrieval | orchestrator, agent tools |
| WorkspaceService | sandboxed FS ops | orchestrator, agent tools |
| CommandExecutionService | sandboxed shell ops | orchestrator, GitService |
| GitService | git operations | orchestrator |
| SnapshotService | snapshot create/restore | orchestrator |
| DocumentationAutoUpdateService | docs regeneration | post-run hook |
| ConsoleEventService | agent_events writes + Redis fan-out | everywhere |
<!-- AUTO-GENERATED:END -->

2. `docs/DATABASE_SCHEMA.md`

# Database Schema

_Last updated by agent run: <run_id> on <ISO-8601 timestamp>_

## Tables

<!-- AUTO-GENERATED:START -->
### `projects`
- **Purpose**: a real software codebase cloned into an isolated server workspace.
- **Columns**:
	- `id` BIGSERIAL PK
	- `name` varchar
	- `slug` varchar UNIQUE
	- `description` text NULL
	- `repository_url` varchar NULL
	- `local_workspace_path` varchar NULL
	- `default_branch` varchar DEFAULT 'main'
	- `current_branch` varchar NULL
	- `framework_detected` varchar NULL
	- `language_detected` varchar NULL
	- `status` varchar DEFAULT 'creating'
	- `created_by` bigint REFERENCES users(id) ON DELETE CASCADE
	- timestamps + soft delete
- **Indexes**: `(status)`, `(slug)` UNIQUE
- **Model relations**:
	- `belongsTo(User::class, 'created_by')`
	- `hasMany(AgentRun::class)`
	- `hasMany(WorkspaceSnapshot::class)`
	- `hasMany(RagChunk::class)`

### `agent_runs`
- **Purpose**: one coding task given to one agent.
- **Columns**: id, project_id, user_id, title, prompt, status, current_step, selected_agent, selected_model, branch_name, started_at, completed_at, failed_reason, metadata_json, timestamps.
- **Indexes**: `(project_id, status)`, `(user_id, created_at)`.
- **Model relations**:
	- `belongsTo(Project::class)`
	- `belongsTo(User::class)`
	- `hasMany(AgentEvent::class, 'run_id')`
	- `hasMany(WorkspaceFile::class, 'run_id')`
	- `hasMany(WorkspaceSnapshot::class, 'run_id')`
	- `hasMany(CommandExecution::class, 'run_id')`
	- `hasMany(GitOperation::class, 'run_id')`

### `agent_events`
- Append-only ledger. See migration for full column set.
- **Indexes**: `(run_id, id)`, `(project_id, created_at)`, `(event_type)`.
- **Relations**: `belongsTo(AgentRun::class, 'run_id')`.

### `workspace_files`
- File-level audit per run.
- **Indexes**: `(run_id)`, `(project_id, path)`.
- **Relations**: `belongsTo(AgentRun::class, 'run_id')`, `belongsTo(WorkspaceSnapshot::class, 'snapshot_id')`.

### `workspace_snapshots`
- Recoverability primitive.
- **Indexes**: `(project_id, snapshot_type)`, `(run_id)`.
- **Relations**: `hasMany(WorkspaceFile::class, 'snapshot_id')`.

### `rag_chunks`
- pgvector-backed memory.
- **Indexes**: `(project_id, source_type)`, `(content_hash)`, ivfflat on `embedding`.

### `agent_providers`, `agent_settings`, `git_operations`, `documentation_updates`, `command_executions`, `run_reviews`, `project_connections`, `personal_access_tokens`
- See migrations for full shapes.
<!-- AUTO-GENERATED:END -->

## Business meaning

<!-- AUTO-GENERATED:START -->
- **projects**: real codebases under management.
- **agent_runs**: the unit of work and audit. Everything else references a run.
- **agent_events**: the live ledger that powers the console.
- **workspace_files**: what was actually touched and how.
- **workspace_snapshots**: how to recover.
- **rag_chunks**: what the agent knows about the project.
- **agent_settings**: runtime configuration (with secrets, encrypted).
<!-- AUTO-GENERATED:END -->

3. `docs/ARCHITECTURE_DIAGRAMS.md`

# Architecture Diagrams

_Last updated by agent run: <run_id> on <ISO-8601 timestamp>_

## High-level system

<!-- AUTO-GENERATED:START -->

flowchart LR

User(["iPhone / Web user"]) -->|REST + SSE| API["Laravel API"]

API --> Orchestrator["AgentRunOrchestrator"]

Orchestrator --> Providers{"Provider"}

Providers --> OAI["OpenAI"]

Providers --> CLA["Anthropic"]

Providers --> CC["Claude Code CLI"]

Orchestrator --> RAG["RagContextService"]

Orchestrator --> WS["WorkspaceService"]

Orchestrator --> GIT["GitService"]

Orchestrator --> SNAP["SnapshotService"]

Orchestrator --> DOCS["DocumentationAutoUpdateService"]

Orchestrator --> EVT["ConsoleEventService"]

WS --> FS[("Project workspace FS")]

RAG --> PG[("PostgreSQL + pgvector")]

EVT --> PG

SNAP --> S3[("Object store")]

<!-- AUTO-GENERATED:END -->

## Agent run lifecycle

<!-- AUTO-GENERATED:START -->

stateDiagram-v2

[*] --> draft

draft --> queued: start()

queued --> running: worker picked up

running --> waiting_for_user: agent needs input

waiting_for_user --> running: user responds

running --> paused: user pause()

paused --> running: resume()

running --> completed: final_summary

running --> failed

running --> cancelled

completed --> [*]

<!-- AUTO-GENERATED:END -->

## RAG indexing flow

<!-- AUTO-GENERATED:START -->

flowchart LR

A["file changed"] --> B["Detect source_type"] --> C["Chunk"] --> D["Hash"] --> E{"hash exists?"}

E -- yes --> X["skip"]

E -- no --> F["OpenAI embeddings"] --> G["Upsert rag_chunks"] --> H["emit rag_chunk_indexed"]

<!-- AUTO-GENERATED:END -->

## File change / revision flow

<!-- AUTO-GENERATED:START -->

flowchart LR

A["agent tool: apply_patch"] --> B["WorkspaceService.validate"] --> C["hash before"]

C --> D["write file"] --> E["hash after"]

E --> F["insert workspace_files row"] --> G["emit file_* event"]

G --> H["trigger RAG incremental index"]

<!-- AUTO-GENERATED:END -->

## Git workflow

<!-- AUTO-GENERATED:START -->

gitGraph

commit id: "main"

branch agent/run-148

commit id: "pre_run snapshot"

commit id: "feat: …"

checkout main

merge agent/run-148 tag: "user-approved"

<!-- AUTO-GENERATED:END -->

## iPhone app API flow

<!-- AUTO-GENERATED:START -->

sequenceDiagram

participant iOS as iPhone

participant API as Laravel API

participant W as Horizon worker

participant P as Provider

iOS->>API: POST /api/runs (draft)

iOS->>API: POST /api/runs/{id}/start

API->>W: enqueue RunAgentJob

W->>P: startRun(ctx)

P-->>W: stream events

W->>API: persist agent_events

API-->>iOS: SSE events/stream

iOS->>API: POST /api/runs/{id}/resume (input)

<!-- AUTO-GENERATED:END -->

## Database relationship diagram

<!-- AUTO-GENERATED:START -->

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

PROJECTS ||--o{ RAG_CHUNKS : indexed_into

<!-- AUTO-GENERATED:END -->

4. Generation rules (binding for the Documentation Agent)

Always replace only content within  / .

Keep stable ordering (alphabetical within sections; routes ordered by path).

Use absolute paths from project root (e.g. app/Http/Controllers/Api/ProjectController.php).

Use — (em dash) for empty cells.

Never include secret values; redact tokens to sk-…XXXX.

Validate Mermaid before write.

1. docs/PROJECT_MAP.md

2. docs/DATABASE_SCHEMA.md

3. docs/ARCHITECTURE_DIAGRAMS.md

4. Generation rules (binding for the Documentation Agent)

1. `docs/PROJECT_MAP.md`

2. `docs/DATABASE_SCHEMA.md`

3. `docs/ARCHITECTURE_DIAGRAMS.md`