moloapp/plans/README.md

# MoloApp Detailed Plans

Index for the ten detailed plan files. Each file is self-contained with purpose, best practices, structure, rules, guidelines, specifications, execution steps, validation, references, open questions, and sources.

## Index

| # | File | Title | Scope (one line) |
|---|------|-------|------------------|
| 1 | 01-runtime.md | Core Runtime and HTTP Fundamentals | Event loop, lifecycle, HTTP/1.1 + HTTP/2, compression, cookies, static. |
| 2 | 02-observability.md | Observability Backbone | Logging, typed events, metrics, tracing, correlation, zero-cost gating. |
| 3 | 03-security.md | Security | TLS wolfSSL, auth, hashing/crypto, sessions, guards, upload safety. |
| 4 | 04-data.md | Data Layer | ORM dual backends, self-healing, pooling, transactions, KV, cache, pubsub. |
| 5 | 05-request-routing.md | Request/Response, Routing, Views, Templates | App, routers, views, validation/forms, negotiation, templates, middleware, DI, errors. |
| 6 | 06-realtime.md | Realtime (WebSocket, SSE, Socket.IO, Streaming, WebDAV, Client Parity) | Live protocols plus streaming plus WebDAV, every one with client parity. |
| 7 | 07-supervisor-replication.md | Supervisor, Tasks, Replication | Process supervisor, background tasks, pubsub durability, replication, multi-instance. |
| 8 | 08-clients-openapi.md | Clients, OpenAPI, Test Client | HTTP/REST client, REST standards, OpenAPI generation, test client. |
| 9 | 09-cli-ops.md | CLI Tooling, Dev Server, Operations | CLI, dev server, embedder, AI harness, health/metrics, i18n/CSP. |
| 10 | 10-workflow-example.md | Workflow, Testing Discipline, Living Example | Specs, AGENTS.md, autonomous git, integration testing, living example. |

## How files reference each other

- References always use exact sibling filenames (`01-runtime.md` through `10-workflow-example.md`).
- Each file has a References section naming Depends on (interfaces it consumes) and Feeds (interfaces it provides).
- Dependency direction (consumes, upstream first):
  - `01-runtime.md` depends on `02-observability.md` (hooks) and `03-security.md` (TLS handle); feeds `05-request-routing.md`, `06-realtime.md`, `08-clients-openapi.md`, `09-cli-ops.md`.
  - `02-observability.md` depends on `01-runtime.md` (lifecycle hooks); feeds `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`, `10-workflow-example.md`.
  - `03-security.md` depends on `01-runtime.md` and `02-observability.md`; feeds `04-data.md`, `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `09-cli-ops.md`, `10-workflow-example.md`.
  - `04-data.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`; feeds `05-request-routing.md`, `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `10-workflow-example.md`.
  - `05-request-routing.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`; feeds `06-realtime.md`, `07-supervisor-replication.md`, `08-clients-openapi.md`, `09-cli-ops.md`; follows `10-workflow-example.md`.
  - `06-realtime.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `05-request-routing.md`; feeds `04-data.md` (pubsub bridge), `07-supervisor-replication.md`, `08-clients-openapi.md`, `10-workflow-example.md`.
  - `07-supervisor-replication.md` depends on `01-runtime.md`, `02-observability.md`, `04-data.md`, `06-realtime.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`.
  - `08-clients-openapi.md` depends on `01-runtime.md`, `02-observability.md`, `03-security.md`, `04-data.md`, `05-request-routing.md`; defers realtime clients to `06-realtime.md`; feeds `09-cli-ops.md`, `10-workflow-example.md`.
  - `09-cli-ops.md` depends on `01-runtime.md` through `08-clients-openapi.md`; feeds `10-workflow-example.md`.
  - `10-workflow-example.md` depends on `02-observability.md`, `08-clients-openapi.md`, `09-cli-ops.md`; feeds `01-runtime.md` through `09-cli-ops.md` (spec template, test discipline, release gates).

## Overall execution order

Build order follows plan.md section 10, with the file sequence matching dependency order:

1. `01-runtime.md` steps 1-10 plus `02-observability.md` steps 1-10 (plan step 1: foundation and instrumentation).
2. `03-security.md` steps 1-10 (plan step 2: TLS, auth, guards, uploads).
3. `04-data.md` steps 1-10 (plan step 3: drivers, ORM, sync/heal, KV/cache/pubsub).
4. `06-realtime.md` steps 1-5 plus `07-supervisor-replication.md` steps E7-1 through E7-4 (plan step 4: realtime base, supervisor and task runner).
5. `05-request-routing.md` steps E1-E12 plus `08-clients-openapi.md` steps 1-8 plus `09-cli-ops.md` steps 1-10 (plan step 5: app layer, clients, OpenAPI, CLI/ops).
6. `07-supervisor-replication.md` steps E7-5 through E7-8 (plan step 6: durable streams, replication, multi-instance).
7. `10-workflow-example.md` steps 1-8 throughout and finally (plan step 7: specs, AGENTS.md, pipeline, living example, autonomous end-to-end run).

Rule: no file is done until its validation section passes through the real stack and `10-workflow-example.md` rule 1 holds (spec updated, docs updated, living example demonstrates it, full suite green, same session).