GF
Giles Flythe Engineers
Reserve Study Platform · Architectural Decisions
v1 · May 2026
6
For GFE Leadership Review

Six choices that compound.

These are the foundational commitments — the ones that make every later workstream additive rather than complicated. Aligning on them now turns the rest of the build into execution and gives GFE a platform that gets sharper with every report delivered.

Audience
GFE Leadership & Engineering
Decision Class
Foundational · Pre-Build
Prepared by
Jason Cooper · wyth.ai
01
Choice One

The JSON contract is the spine.

The keystone of the entire system is a versioned data contract — a structured ReserveStudy payload that flows through every component. Intake produces it. The generator consumes it. QA validates it. The platform mirrors it. The corpus archives it.

The contract is designed once, with the API-integrated end-state as a forward-looking constraint, so the schema we ship in the standalone tool is the same schema that flows through the platform API later. Every workstream plugs into the same shape, which means every new capability is additive — the contract grows, and the system grows with it.

ReserveStudy JSON · v1 Smart Intake Generator QA Suite Platform Reports Corpus
02
Choice Two

Engineer judgment is captured upfront.

When an engineer's judgment about a community — condition ratings, component sub-attributes, sub-area assignments, cost variances — is captured in structured fields at the moment the call is made, the system gets a richer, more reliable picture than it could ever reconstruct from cells later.

The Smart Intake form takes over the engineer-facing input surface — replacing the slower screens of the funding plan app and pushing structured data directly into its backend via API. The engineer captures judgment once, in context, with the right field types and inline validation. Better inputs mean better outputs — and every component decision the firm makes becomes part of a queryable record the team can search, cite, and learn from.

Excel Workbook RETIRED Smart Intake Form Asphalt Paving Good Roofing Fair Pool · 2 Good Clubhouse HVAC Review Mailbox Stations Good Retaining Walls Good ENGINEER · STRUCTURED CAPTURE
03
Choice Three

The template file disappears.

The renderer becomes a Python module that builds every report from clean code — every time. Cover page, headers, financial tables, signature block — all assembled programmatically from the validated ReserveStudy payload. Same code path, every community, every quarter.

The visual identity of a GF report becomes versioned, testable, and absolutely consistent. When the design needs to evolve — a new section, a refreshed cover, a Board-requested tweak — the change ships everywhere at once. No migrating templates, no per-report drift, no surprises.

Report Template CARRYOVER BUGS def render(): doc.add(...) doc.add(...) return doc code { community, components, financials } JSON Clean .docx PROGRAMMATIC
04
Choice Four

The knowledge base is plural and additive.

Voice isn't a single prompt — it's the firm's accumulated craft. The narrative generator retrieves from multiple parallel sources of GF institutional knowledge: vocabulary patterns at the sentence level, historical exemplars from the firm's best delivered reports, component templates by community type, and benchmark cost data.

Every output is informed by GFE's best historical work. As more reports are delivered and reviewed, the corpus grows. The platform inherits the firm's craft — and gives it back, sharper, on every new project.

GF Vocabulary Historical Exemplars Component Templates Cost Database Generator RETRIEVAL-FED voice anchored, plural
05
Choice Five

Flag, never silently fill.

When the system encounters something that benefits from a human eye — an unmatched cost, a component without a clear analog, an interpretation that calls for engineering judgment — it surfaces that span visibly in the draft.

Every flagged span is highlighted in the document, indexed in the engineer-review summary, and accompanied by the reason for flagging. Engineers see exactly what needs their attention; everything else they can trust at a glance. Confidence is encoded into the document, ready for them.

! ! !
06
Choice Six

Deterministic code wraps the creative LLM.

The generator is a layered pipeline. Code handles what code is great at — ingestion, validation, section planning, QA, rendering — all testable, debuggable, version-controlled. The LLM handles what it's great at — narrative generation, bounded by structured Pydantic outputs and validated by deterministic QA on every side.

Each layer gets the engineering treatment it benefits from. Software practices apply where they work best; iterative prompt refinement applies where it works best. The result is a system that's both reliable and expressive — maintainable for the long haul, alive in the writing.

Ingest Schema check Plan Section graph LLM Core structured outputs CREATIVE QA Deterministic Render .docx DETERMINISTIC SHELL DETERMINISTIC SHELL CREATIVE INTERIOR
The Lineage

What stays. What extends. What's replaced. What's new.

Every component of GFE's current workflow is accounted for. Most of what works keeps working; the parts that have produced embarrassments get retired; a small set of new capabilities is added. Nothing is silently dropped.

Preserve
Extend
Replace
Add New
Funding Plan App · backend
Cash-flow projections, threshold analysis, alternative modeling. The computation engine stays — it's the financial source of truth.
GF Voice & Vocabulary
Curated patterns carry forward as prompt inputs.
Historical Exemplars
The firm's best past reports join the knowledge base as voice anchors.
Email Pipeline
Inbox fetch + send dispatcher remain.
Narrative Generation
Existing logic extended into a versioned, retrieval-fed engine.
Lessons Learned Corpus
Becomes the input to an approval-gated learning loop.
QA Pass
Promoted from skill checklist to deterministic test suite.
Past Report Library
Indexed for vector retrieval and starting-template match.
Excel as Engineer Input
Retired in favor of structured form capture.
Report Template.docx
Replaced by programmatic renderer — no template file in the loop.
Funding Plan App · UI
The slow engineer-facing screens — including the duplicate-and-zero-out flow — are replaced by the Smart Intake form, which writes to the FPA backend via API.
Skill-Bundle Generator
Replaced by a code-first generator (shadow mode during cutover).
Smart Intake Form
Wizard for structured capture of engineer judgment.
ReserveStudy JSON Schema
Versioned data contract spanning intake → generator → platform.
Starting-Template Match
Pre-fill from the closest past community by component profile.
Cost-Variance Flags
Inline reconciliation against the internal cost database.
Self-Learning Loop
Diff extraction from reviewer corrections, gated by approval.
The Architecture

What these choices produce.

The six choices above compose to a single architecture — visualized here in isometric form. Toggle between the build phases to see how the same data contract carries the system from standalone intake through API integration to a unified platform.

Phase 1 · Engineer → Intake → Contract → Generator
Live · Click to morph
QA Suite NEW Engineer · PE Smart Intake NEW ReserveStudy JSON CONTRACT Funding Plan App PRESERVE Report Generator EXTEND SIGNED Signed Report KNOWLEDGE BASE · EXTEND Vocabulary Historical Exemplars Component Templates Cost Database Unified Platform
Smart Intake produces the ReserveStudy JSON contract. Generator consumes it directly. Funding plan app stays in its current form, untouched.
Six commitments. A platform that compounds with every report.
The thesis · in one line

Each of these choices stands on its own — defensible, measurable, additive. Together, they compose to a system that's both reliable and expressive: one where the firm's craft compounds, the engineering team works at a higher level, and every reserve study delivered makes the next one better.

The build plan that follows from these choices — the workstreams, the integrations, the platform extensions — is downstream of this alignment. We're not debating how to build the system right now. We're aligning on the shape of what we're building together. Everything else flows from that shape.

With these six commitments in place, Claude Code has a foundation to build against, and GFE has a platform worth investing in for the long term — one the firm will be proud to show clients, train new engineers on, and grow alongside.