ADR 003: Consolidate on Flask Instead of Go/SvelteKit Rewrite
Status: Accepted — supersedes the Go/SvelteKit rewrite plan
Context: Long-term platform architecture
Context
SeedTrust currently runs multiple application surfaces: a Flask monolith, a FastAPI service built alongside it, a Next.js PWA, and a separate new-st Go/SvelteKit shell/experiment. Earlier planning proposed replacing the existing system with a clean-slate Go backend and SvelteKit frontend.
That direction solved some real problems, but it also added another major technology stack and increased the amount of software that must reach parity before the platform becomes simpler. The current pain is not just old code; it is the number of codebases, auth systems, frontend patterns, and deployment surfaces a developer must understand to make safe changes.
Key problems to solve:
- Too many codebases. Flask, FastAPI, Next.js, and
new-stsplit product behavior across several frameworks. - Business logic is duplicated or split. Some features exist only in Flask (NACHA, full RBAC, report generation); others only in FastAPI (Huntington, push notifications).
- Auth is fragmented. Flask uses session cookies; FastAPI uses custom JWT; Next.js wraps FastAPI JWT via NextAuth.
- The migration target must reduce complexity. A rewrite that adds Go/SvelteKit before reaching parity delays the simplicity goal.
Decision
Do not make the Go/SvelteKit rewrite the strategic destination. Consolidate SeedTrust into seedtrust_flask as the single primary application.
| Layer | Target Direction |
|---|---|
| Primary app | seedtrust_flask |
| UI | Jinja/server-rendered pages enhanced with Alpine and HTMX |
| Dynamic data | JSON endpoints feeding partials where needed |
| Auth | Move toward Flask-owned session/auth flows |
| Existing FastAPI | Maintain and backfill into Flask over time |
| Existing Next.js | Maintain only as needed during consolidation |
new-st | Shell/experiment; not the product destination |
Key design choices:
Optimize for simplicity over novelty. The goal is fewer services, fewer auth paths, fewer deployment surfaces, and less context switching.
Use Flask as the consolidation point. Flask already owns many financial-critical admin workflows, RBAC, NACHA, reports, cron behavior, and server-rendered UI. New product work should strengthen that center instead of creating a fourth permanent surface.
Preserve both banking paths. Huntington (CA) and NACHA (all other states) are preserved as separate banking modules. The routing logic is migrated, not redesigned.
Prefer progressive enhancement. Build pages as server-rendered Jinja first. Use Alpine for local UI state and HTMX for partial refreshes or form interactions. Use JSON APIs where partials need data without a full page load.
Retire duplicate surfaces gradually. FastAPI, Next.js, and new-st should remain stable while they have production responsibility, but new ownership should move toward Flask.
Consequences
Positive:
- One strategic codebase and simpler onboarding model
- Lower parity risk than a clean-slate rewrite
- Existing Flask RBAC, admin workflows, reports, and banking operations remain close to the product center
- Less frontend/backend type drift because pages and partials can be rendered by the same app
- A smaller tech stack that is easier to operate and reason about
Negative:
- Flask still contains large legacy files that need careful incremental improvement
- Some modern API/mobile behavior must be ported back into Flask thoughtfully
- The team must avoid simply growing Flask monolith files; consolidation still needs service/helper boundaries and tests
- FastAPI and Next.js must remain maintained until their workflows are replaced or retired
Current State
As of May 2026, Flask and FastAPI remain production systems, the Next.js PWA remains a production surface, and new-st/ exists as a Go/SvelteKit shell/experiment. The product direction is now Flask-only consolidation rather than a Go/SvelteKit rewrite.
See also: Migration Guide, ADR 001: FastAPI Alongside Flask