Updating Documentation

Setup

Install MKDocs

pip install -r requirements.txt

This installs mkdocs-material and its dependencies.

Local Preview

pnpm docs:serve

Opens a live-reloading server at http://127.0.0.1:8000. Changes to markdown files are reflected immediately.

Build

pnpm docs:build

Produces a static site in docs-site/ (git-ignored).

Deploy

pnpm docs:deploy

Builds the site and deploys to Cloudflare Pages project task-time-docs.

---

Adding New Pages

1. Create the markdown file in the appropriate directory under docs/:
2. Architecture docs: docs/architecture/
3. Guides: docs/guides/

4. Contributing: docs/contributing/

5. Add to nav in mkdocs.yml:

   nav:
     - Section Name:
       - Page Title: path/to/file.md
   

6. Preview locally with pnpm docs:serve to verify rendering

---

Mermaid Diagrams

MKDocs Material supports Mermaid diagrams via the pymdownx.superfences extension. Wrap diagrams in fenced code blocks:

```mermaid
flowchart LR
    A --> B --> C
```

Common Diagram Types

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence Diagram

sequenceDiagram
    participant A as Client
    participant B as Server
    participant C as Database

    A->>B: Request
    B->>C: Query
    C-->>B: Result
    B-->>A: Response

State Diagram

stateDiagram-v2
    [*] --> Active
    Active --> Inactive: Deactivate
    Inactive --> Active: Reactivate
    Active --> [*]: Delete

Entity Relationship

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains

Tips

• Use TD (top-down) or LR (left-right) for flowchart direction
• Use -->> for dashed arrows (async/return) in sequence diagrams
• Use subgraphs to group related nodes
• Keep diagrams focused; split complex flows into multiple diagrams

---

AI Context Files

The docs/architecture/ai-context/ directory contains machine-readable markdown files optimized for Claude Code consumption. These are not included in the MKDocs nav and are not part of the documentation site.

When updating architecture (adding endpoints, tables, integrations), update both:

1. The MKDocs page (in docs/architecture/)
2. The AI context file (in docs/architecture/ai-context/)

The AI context files are more concise and table-heavy, designed for quick scanning by AI agents. The MKDocs pages include diagrams, explanations, and examples for human readers.

---

File Structure

docs/
├── index.md                          # Landing page
├── architecture/
│   ├── overview.md                   # Architecture overview (MKDocs)
│   ├── api-endpoints.md              # API reference (MKDocs)
│   ├── dynamodb-tables.md            # Database reference (MKDocs)
│   ├── integrations.md               # Integration flows (MKDocs)
│   ├── status-workflows.md           # Status machines (MKDocs)
│   ├── env-variables.md              # Config reference (MKDocs)
│   ├── web-app.md                    # Web portal structure (MKDocs)
│   └── ai-context/                   # AI agent context (NOT in MKDocs nav)
│       ├── api-endpoints.md
│       ├── dynamodb-tables.md
│       ├── integrations.md
│       ├── status-workflows.md
│       ├── env-variables.md
│       └── web-app.md
├── guides/
│   ├── configuration.md
│   ├── deployment.md
│   └── adding-features.md
└── contributing/
    └── updating-docs.md

---

Style Guide

• Use ATX-style headers (#, ##, ###)
• Use tables for structured data (endpoints, variables, fields)
• Use Mermaid diagrams for flows, state machines, and relationships
• Use admonitions for warnings and notes:

  !!! warning
      Important caveat here.
  
  !!! info
      Helpful context here.
  

• Keep pages focused on one topic
• Link between pages using relative paths: [Configuration](../guides/configuration.md)