ADR-0001: Internal Developer Documentation & ADR Platform
one private, searchable home for every guide, decision, and repo's docs — live in days, growing (only if it earns it) into an LLM assistant over our own knowledge. Also the first worked example of the ADR format; full architecture: Documentation Platform.
Context
Propel's docs are scattered — per-repo READMEs, tribal knowledge, ad-hoc files — with no single discoverable home and no record of why decisions were made. A growing key-person risk as we add clients and engineers.
flowchart TD
A[repo READMEs] --> DEV([engineer hunting
for answers])
B[tribal knowledge] --> DEV
C[ad-hoc docs] --> DEV
D[decisions never recorded] --> DEV
classDef x fill:#FEF1F1,stroke:#E5484D,color:#7a1f22;
class A,B,C,D x;
We want one internal docs platform: aggregates repo docs, captures ADRs, is private with SSO on AWS, doesn't depend on a fragile tunnel, and can later host an LLM assistant over our own docs.
Decision TBD
Suggested decision — not yet agreed, expand to review
Adopt the platform vision, but execute it crawl → walk → run — commit now only to the crawl (a simple private static site) and expand only when each gate is met. Don't build the backend before the docs prove they're used.
flowchart LR
C["🐢 CRAWL
static site + SSO
~$0–15/mo"] -->|used & docs piling up?| W["🚶 WALK
auto-aggregate repo docs
+~$0"]
W -->|content growing, discussion needed?| R["🏃 RUN
comments + LLM backend
+$45+/mo + ops"]
C -.->|enough?| STOP[stay static — fine]
style C fill:#EDEDFF,stroke:#3B54F7
style R fill:#F3EDFF,stroke:#8A54E8
| Phase | Ship | Gate to advance |
|---|---|---|
| Crawl | Simple static site (this content), private SSO | Is it actually used, and are we hand-copying docs? |
| Walk | Repo doc aggregation (future ADR) | Is content growing across many repos? |
| Run | ADR comments + LLM assistant (backend) | Is in-place discussion / doc Q&A worth the backend $ + ops? |
Target architecture (the "run" end-state) stays Stack B, all-AWS so the crawl doesn't paint us into a corner: static hosting on CloudFront/S3 (or Cloudflare for the crawl) → add API GW + Lambda + DynamoDB + Bedrock later.
Consequences
Positive — value in days, not months; spend/ops scale only with proven need; no premature backend; each phase is reversible. Negative — the crawl won't have comments/LLM (by design); advancing later means a (planned) hosting/auth step-up. Risks — stalling at crawl is an acceptable outcome, not a failure; doc rot mitigated by treating generated docs as build artifacts and PR-reviewing hand-written docs.
Alternatives considered (with cost, ~12 users)
| Option | Cost / mo | Why not (as the platform) |
|---|---|---|
| Build full backend now | $45+ + ops | Premature — no proof the docs are used; that's why we crawl first. |
| GitHub Pages | +~$204 (private Pages needs Enterprise $21/user vs Team $4/user × 12) — or $0 if already on Enterprise | Static-only (never hosts comments/LLM); private access requires the Enterprise upgrade. |
| Confluence / Notion | ~$60–180 ($5–15/user) | Not in-AWS, per-seat, weak code-generated-docs story, hard to plug our own LLM in. |
| Cloudflare (Pages + Access) | ~$0–15 | Genuinely viable — kept as the leading crawl option (ADR-0001.1). |
| Self-host Docusaurus on ECS now | ~$175+ | Overkill before value is proven. |
Open questions
- Crawl hosting pick (GitHub Pages vs Cloudflare vs S3/CloudFront) → ADR-0001.1.
- Vector store for the LLM (run phase): pgvector vs OpenSearch Serverless → future ADR.
- Inline (anchored) comments → future ADR.
Discussion
Persistent comments (a "run"-phase feature) will render here once the backend ships — the dogfood target. Until then, discuss in #cloudops.