Gallopify Application Map
What we have built, what each piece solves, and what is coming. Every other wiki page is linked from here.
Gallopify is a financial platform for homeowners' associations (HOAs) and the community-management companies (CMCs) that manage them. One web application (dashboard.gallopify.com, Next.js frontend + FastAPI backend on Neon Postgres) serves both sides of the same management relationship: reserve-project planning and cashflow projection, reserve-fund investment recommendations, reserve-study document ingestion, bank-transaction categorization against capital projects, and dashboards and board reporting on top of all of it.
Reality check
Read this before trusting any demo or screenshot.
- Trade execution does not exist. The investment engine produces an advisory purchase recommendation; a human executes the purchases. There is no trading, rebalancing, or brokerage integration today (the Schwab custodian project is the path toward that).
- Bank-statement ingestion does not exist. "Bank connected" during onboarding is a UI-only flag; only a manually entered cash balance is persisted. Plaid or similar is a future integration.
- Document-ingestion v2 is built but not live. The code is merged and deployed, but production intake is paused and no property has ever cut over — verified inactive 2026-09-07. See the activation runbook.
- Database row-level security is inert. Policies are installed but production connects as the table owner, which bypasses them; the application-layer visibility predicate is the sole live gate — verified inactive 2026-09-07. See the activation runbook.
- Some rendered numbers are stubs. The board packet's health score is derived from an MD5 hash (55–70 range), and its reserve-funding and budget-performance figures are static placeholders. All 925 rows of the investment catalog are placeholder instruments; real instrument sourcing is future work.
The applications
Identity, tenancy & authorization
Who a user is, which organization they belong to, and which properties they can see and act on. Exactly two org types (HOA, CMC) in Clerk; the property is the atomic entity in our database; one visibility predicate (canSee) drives every read for every role.
Onboarding
Dashboard-first and optional: a required profile modal (name, persona, role) provisions the Clerk org — plus a placeholder property for HOAs — and the user lands on a usable dashboard immediately. Remaining setup (org profile, team invites, bank balance, first upload) is progressive dialogs behind a "needs setup" state. No mandatory wizard.
Team & management relationships
Per-property rosters (HOA board members + the assigned property manager, composed at read time across orgs), Org-Admin-gated invites and role changes, CMC↔HOA linking by board-member email with in-app consent (accept is a conditional atomic update), and CMC-side offboarding requiring portfolio-manager approval. Notifications carry the pending actionables and outcome events.
Document ingestion (reserve studies)
Upload a reserve-study PDF → durable extraction via a black-box engine → internal ops review beside the real PDF → conservative reconciliation against existing projects → one atomic release → customer archive decision for projects the new study no longer lists. Gallopify owns all state; the engine owns only transient compute.
Financial planning
The HOA-facing planner and money pages. Projects are expense cashflows with table, Gantt, and active-projects views. Cashflow shows 5-year projections. Transactions categorizes bank transactions against capital projects: a transaction is categorized when it is linked to a project or explicitly marked an operating expense (mutually exclusive); per-project spend rollups are computed backend-side, and the invariant is that spend shown per project equals the sum of its categorized transactions. Deleting a project returns its transactions to the uncategorized queue.
Expense classification
Project-type classification is lazy and read-triggered: listing projects batch-embeds unclassified names with OpenAI and matches them against eight project-type embeddings (cosine similarity, 0.35 floor, "Other / Miscellaneous" fallback). The database column is the cache; degradation is deliberately silent — on API failure categories stay null and retry on the next read. Taxonomy below.
Investment allocation
Recommends how to place idle reserve cash into CDs and treasuries: liquidity-needs analysis over buffered cashflows, a capped greedy fill, geometric maturity laddering, and FDIC-insurance-aware product matching against the catalog. Output is a one-shot purchase recommendation.
Board packet (reporting)
A 3-page PDF summarizing an HOA's financial position: cover; executive summary (KPI cards, portfolio status, allocation charts); algorithm explanation, cashflow projections, top capital expenses, and board-approval signature blocks. Rendered HTML-to-PDF (Jinja2 + headless Chromium, inline SVG charts), capped at two concurrent renders.
Analytics & dashboards
For management companies: a data explorer (dynamic queries over linked HOA data, validated against a 7-column whitelist), an executive dashboard (portfolio KPIs, per-HOA health scores — Good ≥ $500K cash + investments, Caution ≥ $100K, Critical below), and a day-to-day management dashboard. Design sources and intentional deltas: dashboard design reference.
Platform administration
Cross-tenant tooling for platform admins: platform-wide dashboard, investment preview/generation, and maturity-cashflow backfill. The platformAdmin flag is set only out-of-band — never by any self-service path.
Classification taxonomy (reference)
The eight type names are the exact strings stored on the cashflow row; the descriptions are the embedding anchor texts the classifier matches against — prompt-engineering knowledge carried verbatim.
| Type | Embedding description |
|---|---|
| Roofing | Roofing, roof coverings, underlayment, flashing, roof drains, scuppers, gutters, downspouts, shingles, tiles, membrane |
| Exterior Building Components | Exterior building components, siding, stucco, EIFS, exterior paint, coatings, sealants, caulking, windows, exterior doors, balconies, building envelope, facades |
| Paving & Site Improvements | Paving, site improvements, asphalt, concrete, sealcoating, striping, sidewalks, curbs, gutters, parking lot, driveways, walkways |
| Mechanical / Electrical / Plumbing (MEP) | Mechanical electrical plumbing, MEP, boilers, chillers, HVAC, water heaters, pumps, electrical equipment, site lighting, fire alarm panels, generators, transformers, plumbing pipes, water tanks |
| Amenities | Amenities, pool, spa, clubhouse, fitness room, playground, sports court, tennis court, BBQ, site furniture, recreation facilities, gym equipment |
| Interior Common Areas | Interior common areas, flooring, paint, ceilings, lighting, wall finishes, hallways, lobbies, corridors, elevators, laundry rooms, carpet, tile |
| Landscaping & Irrigation | Landscaping, irrigation, trees, shrubs, controllers, valves, sprinkler, lawn, garden, plants, mulch, drainage |
| Other / Miscellaneous | Other miscellaneous, fencing, signage, mailboxes, retaining walls, security gates, trash enclosures, storage |
What does not exist (deliberately stated)
- Trade execution — the allocation output is advisory; a human buys the products. Non-goals also include rebalancing and tax optimization.
- Bank linking — no Plaid or equivalent; the onboarding "Connect bank" dialog persists only a cash balance.
- Bank-statement and budget document uploads — the upload page is reserve-study-only; the other document types are disabled "Coming soon" tasks.
- Forgot-password flow — lost passwords are reset via the Clerk dashboard/API.
- Real investment instruments — every catalog row is a fake placeholder; demo holdings deliberately reference existing rows so they inherit real instruments for free when sourcing lands.
Data & external services
Clerk owns organization identity and membership — there is no organizations table. The application database hangs everything off the property.
| Table | Purpose |
|---|---|
properties | The community entity and stable domain key: HOA/CMC org links, manager assignments, profile, cash balance, fiscal year, lifecycle marker |
management_requests | Outstanding CMC↔HOA offers only; the active relationship lives on the property's CMC link |
offboarding_requests, notifications | PM→PfM offboarding approvals; recipient-filtered event feed |
upcoming_cashflows | Unified cashflow entries — projects are expense-type rows; classification writes the category here |
transactions | Bank transactions, linkable to a project cashflow or flagged operating |
investments, investments_catalog | Per-property holdings; the global (placeholder) product catalog |
documents + pipeline tables | The ingestion pipeline's state: attempts, revisions, reviews, reconciliations, releases, archive decisions, audit events |
Two conventions that are easy to misread from types alone: fiscal_year_start stores a month as the full date 2000-MM-01, and cash_balance is an integer in cents.
| External service | Role |
|---|---|
| Clerk | Authentication, user/org identity, membership metadata, JWT claims |
| Neon Postgres | Primary database (RLS policies installed, enforcement inert) |
| AWS S3 | Per-environment versioned reserve-study source storage; constrained browser POST, exact-version reads |
| Extraction service | Black-box reserve-study extraction behind a strict submit/status/result boundary |
| OpenAI | Project-type classification embeddings |
Security posture, honestly
- The application-layer
canSeepredicate is the live authorization gate on every property-scoped read; database RLS duplicates it by design but is currently inert (owner connection bypasses it). - Authority-sensitive mutations (invites, role changes, linking, offboarding) re-read membership from Clerk at write time rather than trusting JWT claims.
- Flagged, unverified: the board-packet generate endpoint takes a caller-supplied organization id, and the corpus records row-level security as its effective scoping boundary. With RLS inert, whether the app-layer predicate independently covers that route has not been positively verified — treat as an open verification item.
What's coming
The roadmap lives in Linear projects — linked, not copied. The projects most relevant to this map:
- Board reporting quality — replaces the board-packet and dashboard stub figures with real computed data.
- Treasury Management: Schwab — Schwab Advisor Services as custodian for HOA fixed-income accounts; the path from advisory recommendations toward executed treasury management. (Altruist is the parallel candidate.)
- Data Extraction Module — a guardrailed wrapper around the extraction tooling with validation and auditing.
- Customer Experience + Analytics — marketing analytics now; product instrumentation once there are real users.
- Knowledge base — this wiki; serving at
wiki.gallopify.comis pending.
Map of content
How the core systems work
- Identity & authorization — the org/property/role model, claim shapes, the one visibility predicate, and lifecycle flows
- How document ingestion works — the reserve-study pipeline: states, invariants, matching, reconciliation, release, object custody
- How investment allocation works — the five-stage allocator, FDIC rules, worked example, and where the live code deviates from the clean description
Operating references
- Frontend platform contract — layers, tokens, component vocabulary, mechanical enforcement, and open cleanup residue
- Dashboard design reference — Figma sources, exact tokens, and intentional design-vs-code deltas
- The push gate (no-mistakes) — the nine-step pre-share validation pipeline and its operating model
- The AI coding fleet — task-class model routing, installing firstmate from the fork, pooled Claude accounts, quota awareness
Runbooks
- RLS activation runbook — switching the app onto the restricted database role · not activated (verified 2026-09-07)
- Upload-pipeline activation runbook — what §13.2 activation still requires · not activated (verified 2026-09-07)
- Local dev-mode runbook — dev Clerk instance, local stack, seed harness · never-public
Never-public operational pages
Tagged wiki-visibility: never-public and listed in never-public.json; excluded from any public serving by construction.
- Production demo accounts — the Summit cohort: personas, sign-in workflow, mailbox model
- Production provisioning ledger — seeder design, persona manifest, catalog rules, client-trust facts, open items
Historical corpus
- Gallopify-Inc/knowledge-base — archived source corpus (mined once, 2026-09-07); holds
PinnacleDecommissionRecord.md, an immutable audit record of a destructive production change