md / framework / 20260420_molino.architecture.md
Molino⺢Pro

20260420_molino.architecture

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdframework
Milestones
⬆ Parent folder📁 archive📁 seeds📝 16DecTuesdayWeekGoals📝 20260320_molino_mlv_mvp_brief📝 20260416_molino-guidebook📝 20260418_FastProductionSAP_MLV📝 20260420_molino.architecture📝 assistant-system📝 dev-prompts📝 README
H1Molino — Architecture (Canonical Rules)
H2Core Identity

Document + Entity Graph system

Truth → Document → Folio → UI → Intent → Actions → DB → Rebuild

H2Structure (strict)

app/(entity)/<entity>/ page.tsx → read-only server orchestrator actions/ → ONLY mutation authority components/ → dumb UI (client) context/ → ephemeral UI state types/ → domain truth api/route.ts → external boundary only

H2Rules (non-negotiable)
  1. No Prisma outside actions
  2. No mutation in pages
  3. API routes are external only
  4. One entity = one folder
  5. UI never owns truth
  6. All writes go through server actions
H2Persistence Pattern

Client intent → emitIntent / setForm → compute helpers (pure) → queueSave / action → Prisma → revalidate → server re-render

H2Document Engine
H3Layers
  • rawBlocks (input)
  • FlowUnits (normalized)
  • pagination (layout)
  • wagons (render)
H3Guarantees
  • deterministic IDs
  • pure transforms
  • pagination = layout only
H2Trip Module Position

Trip = specialized document

  • stops = FlowUnits equivalent
  • normalizeStops = compute layer
  • TripEngine = projection layer
H2Integration Strategy
H3External systems
  • FareHarbor → inventory only
  • Apps Script → output layer (docs, pdf, email, calendar)
H3Principle

Internal = fast path External = adapters only

H2Output Layer (critical)

Trip →

  • PDF
  • Google Doc
  • Email
  • Calendar event

via Apps Script bridge

H2Evolution Path
  1. Stabilize entity patterns
  2. Inline editing (no side tools)
  3. Output automation (Apps Script)
  4. External integrations (FH API)
H2Guiding Principle

"One source of truth, many projections"