Proposals & Architecture Docs
- Structure a technical proposal: problem, approach, plan, team, risks, investment
- Write C4-lite architecture views — context, container, component — for mixed audiences
- Estimate with ranges and confidence levels instead of fake-precise point numbers
- Build a risk register with likelihood, impact, and named mitigations
- Produce a complete proposal for your capstone as if selling it to Harbor & Vane
| Spaced-rep warm-up: due cards incl. Day 164 sections & ACs | 10 min |
| ELI5 + tech read; write the 8-bone skeleton from memory | 15 min |
| Guided: three C4 diagrams + risks, estimates, exec summary | 45 min |
| Practice: the two-reader gauntlet | 15 min |
| Project: finalize the proposal + extract the template | 15 min |
| Quiz + flashcards | 10 min |
Builds on: Day 164 — Requirements — the Harbor & Vane doc · Day 160 — AI system design — architecture reasoning · Day 161 — Production evidence — cost & latency reports
When a family approves a renovation, the architect doesn't hand over structural calculations — but doesn't hand over only a watercolor either. The winning packet zooms: a street-view sketch anyone's grandmother can read (here's your house, here's the new kitchen), a floor plan the family debates doors on, and framing drawings the builder prices from. Same building, three altitudes, one story. Alongside it: what this fixes, what it costs as a RANGE with a reason ("18–24k; the range narrows once we open the wall — old houses surprise"), what could go wrong and what we'll do about it, and what happens next if you say yes.
A technical proposal is that packet. The C4 model gives you the zoom discipline for the drawings: context (your system as one box among the customer's systems — the executive slide), container (the deployable pieces and how data flows — the IT-review slide), component (inside the interesting container — the engineer slide). The prose around it answers the only four questions any buyer has: do you understand my problem? Will your approach work? What does it cost and how long? What could go wrong? Answer those plainly and the proposal sells itself; decorate instead, and even a good plan reads like a brochure.
Proposals are where FDE work converts to revenue and where engineering credibility is spent or earned. Two audiences read them with opposite needs — Marcus skims for value, risk, and price; the IT director reads the container diagram hunting for the data-leaves-our-network arrow — and one document must survive both. Estimation with ranges is a trust technology: point estimates are lies with confidence, and customers have been lied to before. This exact deliverable appears in FDE interview loops ("write a one-page proposal for the case from the last round") and Day 168 grades you on it tomorrow-adjacent; Day 174 adds objections.
The architect's zoom lens — one system, three altitudes
step 1 / 5You must explain the same docs-QA system to a COO, an IT director, and an engineer. One diagram cannot serve all three — so C4 gives you a zoom lens. Level 1, CONTEXT: your system as a single box among the systems and people it touches.
Guided practice
Draw the three C4 altitudes for the Harbor & Vane pilot
20 minWork in docs/proposal_harbor_vane.md (diagrams as fenced text blocks or mermaid if your renderer supports it).
- Context diagram. Boxes: Claims Intake Copilot (yours); claims inbox (email); AS400 (policy system, read-only); ClaimCore (v0: humans type into it — draw THAT arrow from the review UI through Priya, not from your system); model provider (external, with the data-boundary annotation: "PDF text, PII-redacted per DPA, retention N days"). Label every arrow with the data that flows, not just "API".
- Container diagram. Inside the copilot boundary: intake watcher → parsing/extraction service → review UI → audit & eval store; plus the golden-set harness as a first-class container (you sell WITH your eval — Day 160's lesson made commercial). Draw the trust boundary line where the customer's network ends.
- Component diagram for the extraction service only: schema-constrained extractor (Day 110), field validators, policy cross-checker (AS400 read), exclusion flagger, confidence router (low-confidence → human-first ordering in the review UI).
- The altitude test, per diagram: write the ONE question its reader is asking. Context/Marcus: "what touches what, and does our data leave?" Container/IT: "what runs where, and where is the boundary?" Component/their tech lead: "is the interesting part real engineering or magic?" If a diagram answers a question nobody is asking, delete it.
Write the prose: risks, estimates, and the executive summary
25 min- Risk register. Minimum six rows. Must include: scanned-PDF quality (the OCR ghost — mitigation: week-1 sample of 100 real claims, accuracy floor re-negotiated on evidence); ClaimCore import path unverified (mitigation: v0 doesn't need it — human types from review screen; verify for v1); exclusion-flagging false negatives (the $40K scenario — mitigation: flag-recall prioritized over precision + human review mandatory); adoption risk (mitigation: Priya's team co-designs the review UI in week 2); model-provider data terms vs their compliance (mitigation: DPA + Day 159 questionnaire attached); pilot-window slip from customer dependencies (mitigation: the obligations table with dates).
- Estimates. Build the table: extraction pipeline 2–3 wks (medium confidence — format variance is the driver); review UI 1–1.5 wks (high); AS400 read integration 0.5–2 wks (LOW — vintage system, unknown access path; name it as the range-widener); eval harness + labeled sample 1 wk (high — you have done this, cite Day 140). Then the API-cost line from real arithmetic: 50 claims/day × ~30 pages × tokens/page at mid-tier rates — show the multiplication, give a monthly range.
- Plan & obligations. Six weekly milestones, each with a customer obligation and a demo checkpoint (never go dark — Day 167 foreshadow: weekly 15-minute demos beat one big reveal).
- Executive summary, written now that everything else exists: five sentences, numbers included, ending with the dated ask ("30 minutes with you and IT on Thursday to confirm data access").
On your own
The two-reader gauntlet
15 minPrint (or split-screen) your proposal and read it twice, in character.
Pass 1 — Marcus (VP Ops, 4 minutes, phone in hand): he reads the exec summary, skims headings, looks at ONE diagram, jumps to price. Mark every sentence he'd skip and every place he'd stall confused. Does the exec summary alone give him: cost of the problem, shape of the fix, price range, risk posture, next step?
Pass 2 — the IT director (30 minutes, red pen, OCR grudge): he reads the container diagram first, then risks, then hunts for what you DIDN'T say. Write the three questions he asks that the doc fails to answer, then fix the doc.
Deliverable: a changelog of ≥6 edits made because of the two passes, tagged by which reader forced each. If either pass produced zero edits, you weren't in character.
The capstone proposal — sold to Harbor & Vane
Complete docs/proposal_harbor_vane.md as the full packet: exec summary, problem, approach with all three C4 diagrams, six-week plan with customer obligations, success criteria imported verbatim from the Day 164 requirements doc, ≥6-row risk register, ranged estimates with named drivers and real API-cost arithmetic from Day 156, and a dated next-step ask. Also extract docs/templates/proposal_template.md with your per-section quality checks. This proposal is graded again inside Day 168's simulation and defended against objections on Day 174 — write it as the version of record.
Common mistakes & misconceptions
- One diagram for all audiences. The executive drowns in the component view; the engineer distrusts the context cartoon. Zoom levels exist because readers do.
- Point estimates ("the pilot costs $32,400 and takes 41 days"). False precision reads as either naivety or salesmanship; ranges with named drivers read as competence.
- An empty or cosmetic risk register. The IT director KNOWS the risks — an honest register with mitigations is how you take his objections before he raises them.
- Silently widening scope between requirements and proposal to sweeten the deal. The two documents must promise the same v0, or the pilot ends in a dispute you engineered.
- No customer obligations in the plan. When THEIR data access slips two weeks, an obligations-free plan makes it your slip; the table with dates keeps the schedule honest.
- Vague endings ("we look forward to partnering!"). Proposals convert on one small dated ask; without it, even an impressed buyer has nothing to say yes to.
Q1. The IT director should be handed which view first, and why?
Q2. Which estimate line is written correctly?
Q3. Your proposal's success criteria say "≥90% accuracy" but the requirements doc says "≥95%". What is the correct reading of this situation?
Go deeper — curated resources
- arc42 as the long-form companion ↗ — When a pilot graduates to production, the proposal grows into an arc42-shaped architecture doc — same bones, more load-bearing. Your Day 178 capstone architecture doc will borrow its section list.
- All three C4 diagrams drawn with labeled arrows and trust boundary
- Risk register ≥6 honest rows; estimates all ranged with drivers
- Gauntlet changelog shows ≥6 reader-forced edits
- Proposal + template committed; quiz ≥ 2/3
← Back: The approach section is Day 160's design skill made customer-facing; the success criteria import Day 164's acceptance criteria verbatim; the cost arithmetic reuses Day 156's ledger; the data-boundary annotations are Day 159 drawn as arrows.
Forward →: Day 166 builds the prototype this proposal scoped; Day 167 demos it with the narrative this proposal seeded; Day 168 grades a fresh proposal under simulation; Day 173 deepens the investment section into full ROI analysis.
Unlocks: D168 Week 24 Checkpoint: FDE Simulation I · D171 Stakeholders & Trade-off Navigation · D173 ROI, Pricing & Cost Analysis · D178 Capstone Ship & Document