Financial Model Distribution Architecture Analysis

Date: February 12, 2026 Task: N.6.15 — Financial Model Distribution Architecture Author: Claude (Opus 4.6) Status: Recommendation Ready

---

1. Executive Summary

Recommendation: Hybrid Architecture (Option C) — Local CLI + Cloud React GUI

The CODITECT financial modeling tool (coditect_fm.py) should be distributed as a hybrid — available both as a local CLI tool (included with CODITECT Core installation) and as a cloud-hosted React GUI on the existing GKE infrastructure. This leverages the 70% of cloud infrastructure already in production while preserving the zero-dependency local experience.

Key rationale:

• Local CLI is already built and working (ADR-177) — zero additional effort to distribute
• Cloud infrastructure (GKE, Django, React, PostgreSQL, RBAC, billing) is 70% ready
• The two modes serve different user personas (power users vs. casual users)
• Incremental approach: ship local first, add cloud GUI as a product feature

---

2. Current State

2.1 The Financial Modeling Engine

Property	Value
File	analyze-new-artifacts/coditect-financial-model-2026-02-04/coditect_fm.py
Size	2,358 lines
Dependencies	Python 3 stdlib only (core), xlsxwriter (Excel output)
Database	SQLite (local, self-contained)
Architecture	ADR-177: Database-driven with 10 tables, 13 cache triggers, full audit trail
Output Formats	Static XLSX (10 sheets), Formula XLSX (10 sheets), JSON, CSV
CLI Interface	10 subcommands: scenario, seed-defaults, funding, pricing, growth, build, compare, export, import, history
Current Location	Temporary (analyze-new-artifacts/) — NOT in production paths

2.2 Live GKE Infrastructure (Explored 2026-02-12)

Resource	Production State
GCP Project	coditect-citus-prod
GKE Cluster	coditect-citus-dev, us-central1, 3 nodes
Django Backend	v1.23.2-rbac-fix, 10 replicas (HPA 2-10), api.coditect.ai
React Frontend	v1.28.0-downloads, 2 replicas
Studio Web	v1.0.0, studio.coditect.ai
Cloud SQL	PostgreSQL 16, db-custom-2-8192
Redis	BASIC tier, port 6378
Celery	1 worker replica
Namespaces	coditect, coditect-dev, coditect-dms, coditect-pilot, coditect-production, coditect-staging
Ingresses	api.coditect.ai, auth.coditect.ai, studio.coditect.ai
Artifact Registry	4 repos (enterprise, images, internal, docker)
Cloud Run	docs-coditect (documentation sites)

2.3 Django Backend (19 Apps)

Production-deployed apps directly relevant to FM distribution:

App	Relevance	Status
tenants	Multi-tenant isolation for per-user FM models	Production
permissions	48+ RBAC codes, can add financial category	Production
licenses	Tier-based access control (free tier = limited scenarios)	Production
subscriptions	Billing integration for premium FM features	Production
billing	Invoice/export for FM as a paid feature	Production
commerce	Product catalog (add FM as a product SKU)	Production
users	Authentication, JWT, Firebase	Production

2.4 React Frontend

Property	Value
Framework	React 18.2 + TypeScript + Vite 5
Styling	TailwindCSS 3.3
API Client	Axios + TanStack React Query v5
Routing	React Router v6
Forms	React Hook Form + Zod
Pages	25+ existing pages
Services	13 API service modules
Image	coditect-cloud-frontend:v1.28.0-downloads

---

3. Options Analysis

Option A: Local CLI Only

Approach: Move coditect_fm.py to skills/financial-model/, include in CODITECT Core installation, access via /fm command.

Pros	Cons
Zero additional infrastructure	No web-based collaboration
Already working (ADR-177)	No multi-user access
Zero-dependency core engine	No browser-based charts/dashboards
Offline-capable	Export only (no interactive editing)
Ships immediately	Limited to CLI users

Effort: ~4 hours (relocate, update paths, test) Serves: Power users, developers, CLI-first workflows

Option B: Cloud React GUI Only

Approach: Build a PostgreSQL-backed Django app + React pages on GKE. Users access at studio.coditect.ai/financial-models.

Pros	Cons
Full web experience	Requires internet access
Multi-user collaboration	9-12 weeks additional development
Real-time charts/dashboards	Duplicates engine logic (SQLite → PostgreSQL)
Export to all formats	Requires authentication always
Browser-accessible	Higher operational cost

Effort: ~9-12 weeks Serves: Business users, investors, team collaboration

Option C: Hybrid — Local CLI + Cloud React GUI (RECOMMENDED)

Approach: Ship both:

1. Local CLI — coditect_fm.py moves to skills/financial-model/src/, included in CODITECT Core install, SQLite-backed, works offline
2. Cloud GUI — New financial_models Django app + React pages at studio.coditect.ai/financial-models, PostgreSQL-backed, multi-tenant

The two share the same calculation logic but use different storage backends (SQLite local vs PostgreSQL cloud). The cloud version adds collaboration, real-time charts, and artifact export as a web service.

Pros	Cons
Best of both worlds	Two storage backends to maintain
Local works offline, cloud adds collaboration	Calculation engine needs abstraction layer
Ship local immediately, cloud iteratively	More total development effort
Different pricing tiers (free local, premium cloud)	Sync between local/cloud is complex
Power users keep CLI, business users get GUI

Effort: ~4 hours (local), ~9-12 weeks (cloud), phased Serves: All user personas

---

4. Recommendation: Option C — Hybrid, Phased

Phase 1: Local CLI Distribution (Ship Now — 4 hours)

1. Relocate coditect_fm.py from analyze-new-artifacts/ to skills/financial-model/src/coditect_fm.py
2. Update all references in commands, hooks, skills, docs
3. Add to install script distribution (included with CODITECT Core)
4. Self-provision xlsxwriter dependency in skill venv

Phase 2: Cloud API Foundation (Weeks 1-3)

1. Create financial_models Django app with PostgreSQL models
   • Adapt SQLite schema → PostgreSQL with tenant_id RLS
   • Models: FinancialModel, Scenario, Pricing, GrowthRate, FundingRound, ExpenseRatio, Headcount, WorkingCapital, Comparable, ComputedMonth, ModelHistory
2. Implement DRF API endpoints (CRUD, build, compare, export)
3. Add financial permission category to RBAC (ADR-092)
4. Add Celery tasks for async computation

Phase 3: React GUI (Weeks 4-8)

1. Dashboard page at /financial-models — list, create, clone models
2. Model Builder — assumption editors for pricing, growth, funding, expenses
3. Results Viewer — P&L, Revenue, Expenses, Cash Flow with charts (Recharts or Nivo)
4. Scenario Compare — side-by-side with delta highlighting
5. Export — XLSX, Formula XLSX, JSON, CSV, PDF from browser

Phase 4: Premium Features (Weeks 9-12)

1. Collaboration — share models with team members (read/edit/comment)
2. Templates — pre-built SaaS, marketplace, hardware models
3. Benchmarks — industry comparison dashboard
4. Version History — git-like diff for model changes
5. Monetization — Free tier (1 model, 1 scenario), Pro (unlimited), Enterprise (team collaboration)

---

5. Architecture Diagram

                    ┌─────────────────────────────────────────┐
                    │           CODITECT Financial Modeling     │
                    │                                          │
  ┌─────────────┐  │  ┌──────────────┐   ┌───────────────┐   │
  │ Local CLI   │  │  │ React GUI    │   │ Django API    │   │
  │ /fm command │  │  │ React 18+TS  │   │ DRF + Celery  │   │
  │ coditect_fm │  │  │ TailwindCSS  │   │ /api/v1/fm/   │   │
  │ .py         │  │  │ Recharts     │   │               │   │
  └──────┬──────┘  │  └──────┬───────┘   └───────┬───────┘   │
         │         │         │                     │           │
         ▼         │         ▼                     ▼           │
  ┌──────────┐     │  ┌──────────────────────────────────┐    │
  │ SQLite   │     │  │         PostgreSQL 16             │    │
  │ (local)  │     │  │   Cloud SQL + RLS + tenant_id     │    │
  │ fm.db    │     │  │   coditect-citus-dev              │    │
  └──────────┘     │  └──────────────────────────────────┘    │
                    │                                          │
                    │  ┌──────────────────────────────────┐    │
                    │  │     GKE: coditect-citus-dev       │    │
                    │  │  api.coditect.ai (Django x10)     │    │
                    │  │  studio.coditect.ai (React x2)    │    │
                    │  │  Redis (sessions/cache)           │    │
                    │  │  Celery (async compute)           │    │
                    │  └──────────────────────────────────┘    │
                    └─────────────────────────────────────────┘

---

6. Calculation Engine Abstraction

To avoid duplicating logic, extract the calculation engine into an abstract layer:

# Shared calculation logic (no storage dependency)
class FinancialCalculationEngine:
    """Pure calculation — takes assumptions dict, returns projections dict."""
    def compute_model(self, assumptions: dict) -> dict: ...
    def compute_unit_economics(self, monthly_data: list) -> dict: ...
    def compare_scenarios(self, scenario_a: dict, scenario_b: dict) -> dict: ...

# Local backend (SQLite)
class LocalFinancialModelBackend(FinancialCalculationEngine):
    """SQLite storage — current coditect_fm.py"""
    def load_assumptions(self, scenario_id: str) -> dict: ...
    def save_results(self, scenario_id: str, results: dict): ...

# Cloud backend (PostgreSQL via Django ORM)
class CloudFinancialModelBackend(FinancialCalculationEngine):
    """PostgreSQL storage — Django models with tenant isolation"""
    def load_assumptions(self, scenario_id: str, tenant_id: str) -> dict: ...
    def save_results(self, scenario_id: str, tenant_id: str, results: dict): ...

This ensures calculation logic is tested once and shared across both backends.

---

7. RBAC Integration

Add to existing ADR-092 permission system:

Permission Code	Description	Roles
financial.model.create	Create financial models	owner, admin, contributor
financial.model.read	View financial models	owner, admin, contributor, viewer
financial.model.update	Edit model assumptions	owner, admin, contributor
financial.model.delete	Delete financial models	owner, admin
financial.model.export	Export to XLSX/PDF/JSON	owner, admin, contributor
financial.model.share	Share models with team	owner, admin
financial.scenario.create	Create scenarios	owner, admin, contributor
financial.scenario.compare	Compare scenarios	owner, admin, contributor, viewer

---

8. Monetization Strategy

Tier	Local CLI	Cloud GUI	Price
Free	Full engine, 1 scenario	1 model, 1 scenario, export to JSON only	$0
Pro	Unlimited	Unlimited models/scenarios, all exports	Included with CODITECT Pro ($49/mo)
Enterprise	Team sharing via git	Team collaboration, version history, benchmarks	Included with Enterprise ($149/mo)

---

9. Implementation Priority

Priority	Item	Effort	Value
P0	Relocate engine to permanent path	4h	Unblocks everything
P1	Django models + API	2 weeks	Cloud foundation
P1	React dashboard + builder	2 weeks	User-facing value
P2	Charts/visualization	1 week	Presentation quality
P2	Export from browser	1 week	Key workflow
P3	Collaboration	2 weeks	Team features
P3	Templates/benchmarks	1 week	Content value

---

10. Risk Assessment

Risk	Impact	Mitigation
Engine duplication (SQLite vs PostgreSQL)	Medium	Abstract calculation layer shared by both
Local/cloud sync complexity	Low	Don't sync — they're independent modes
GKE resource pressure (adding FM compute)	Low	Celery workers handle async; current 3-node cluster has headroom
PostgreSQL schema migration	Low	Django migrations; existing patterns from 19 other apps
React component complexity (spreadsheet view)	Medium	Use existing library (AG Grid, TanStack Table)

---

11. Existing Infrastructure Reuse

Component	Exists?	Reuse
GKE cluster	Yes	Deploy FM as part of existing django-backend
PostgreSQL	Yes	Add financial_models tables to existing Cloud SQL
Redis	Yes	Cache computed results
Celery	Yes	Async model computation
React frontend	Yes	Add pages to existing coditect-cloud-frontend
RBAC system	Yes	Add financial permission category
Billing/Stripe	Yes	Tier-gate FM features
Artifact Registry	Yes	Deploy updated images
Ingress/DNS	Yes	studio.coditect.ai/financial-models
Cloud Build	Yes	Automated deployment

Reuse percentage: ~70% — only the FM-specific data models, API endpoints, React pages, and calculation abstraction need to be built new.

---

Decision Status: Pending ADR creation Next Steps:

1. Create ADR for FM distribution decision
2. Execute Phase 1 (relocate engine — 4 hours)
3. Begin Phase 2 (Django models — 2 weeks)