Architecture and Repository Orientation - Configuration layering across local, prod, and service-specific runtimes
Overview
This repository does not treat configuration as a single global runtime model. Instead, it splits configuration across local developer tooling, production deployment assets, and service-specific overlays so each execution path can be started, routed, and persisted differently.
The clearest example is the frontend application flow: in local Docker Compose it can merge remote backend data with locally stored submissions, while production can switch to bucket-backed persistence and a different origin model. The backend also has its own runtime defaults and overrides, and the US-facing API contract is documented separately with its own auth and scope rules.
Configuration Surfaces
| Surface | File | Runtime scope | What it controls |
|---|---|---|---|
| Root environment file | .env |
Local developer shell | Variables are exported before Compose starts the stack. |
| Development guide | documents/development.md |
Local workstation | Local startup command, account role overrides, remote application toggle, and frontend storage behavior. |
| Local Compose stack | platform/deployment/local/docker-compose.yml |
Local container runtime | Starts the local service graph for backend, frontend, and supporting services. |
| Local routing layer | platform/deployment/local/Caddyfile |
Local HTTP ingress | Local request routing for the development stack. |
| Production Compose stack | platform/deployment/prod/docker-compose.yml |
Production container runtime | VM-side deployment graph used during SSH-driven rollouts. |
| Production deployment guide | documents/deployment.md |
Production operator workflow | Image pull, schema application, health checks, and rollout sequencing. |
| Frontend production env | frontend/.env.production |
Hosted frontend runtime | Backend URL and origin settings for production, plus optional GCS-backed persistence. |
| Backend runtime defaults | backend/src/main.py |
Backend container runtime | CORS origin defaults and env-driven overrides. |
| US API contract | documents/us-api-v1.md |
US service-specific runtime | Consent, purpose, data-category, and auth header contract. |
Architecture Overview
flowchart TD
subgraph LocalDev [Local Developer Runtime]
RootEnv[Root env file]
DevGuide[Development guide]
LocalCompose[Local docker compose]
LocalCaddy[Caddyfile]
BackendLocal[Backend container]
FrontendLocal[Frontend container]
MySQLLocal[MySQL container]
LocalFiles[Local application data file]
end
subgraph Production [Production Runtime]
ProdEnv[Frontend production env]
ProdGuide[Deployment guide]
ProdCompose[Production docker compose]
SchemaHelper[Schema application helper]
Fastly[Fastly]
GCLB[Google Cloud HTTPS Load Balancer]
BackendProd[Backend container]
FrontendProd[Frontend container]
MySQLProd[MySQL container]
GCSBucket[GCS bucket for applications data]
end
subgraph ServiceSpecific [Service Specific Runtime Contracts]
BackendCors[Backend CORS defaults]
FrontendEnv[Frontend env candidates]
USContract[US API contract]
end
RootEnv --> DevGuide
DevGuide --> LocalCompose
LocalCompose --> BackendLocal
LocalCompose --> FrontendLocal
LocalCompose --> MySQLLocal
LocalCompose --> LocalCaddy
FrontendLocal --> LocalFiles
BackendLocal --> BackendCors
ProdGuide --> ProdCompose
ProdCompose --> BackendProd
ProdCompose --> FrontendProd
ProdCompose --> MySQLProd
ProdCompose --> SchemaHelper
Fastly --> GCLB
GCLB --> FrontendProd
GCLB --> BackendProd
FrontendProd --> ProdEnv
FrontendProd --> GCSBucket
FrontendEnv --> FrontendLocal
FrontendEnv --> FrontendProd
USContract --> BackendProd
Configuration Layering in Practice
Local developer runtime
Note: The repository intentionally uses different configuration surfaces for local, production, and service-specific runtimes. The local Compose stack, production Compose stack, and frontend runtime envs coexist rather than being merged into a single universal
.envmodel.
Local startup is shell-driven first, container-driven second. The documented workflow exports variables from .env before docker compose -f platform/deployment/local/docker-compose.yml up -d --build, which means Compose receives already-expanded values instead of relying on a single baked-in runtime image.
The local stack is also feature-aware. documents/development.md shows that ADMIN_EMAILS and REALTOR_EMAILS can promote accounts into reviewer roles, ENABLE_REMOTE_APPLICATIONS or NEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONS controls whether the frontend merges backend applicants, and APPLICATIONS_DATA_FILE controls where submissions are written inside the frontend container.
Production runtime
Production is deployed from platform/deployment/prod/docker-compose.yml through SSH-driven rollouts on Compute Engine. The production guide uses docker-compose down, docker-compose pull, and docker-compose up -d --build, which keeps production config anchored to the deployment directory rather than to a workstation shell.
The production frontend env file uses a different surface from local development. frontend/.env.production sets VITE_BACKEND_API_URL=https://app.joinlita.com and ALLOWED_ORIGINS=https://app.joinlita.com, and the deployment docs add optional APPLICATIONS_DATA_GCS_BUCKET and APPLICATIONS_DATA_GCS_OBJECT settings when the frontend should persist submissions to Google Cloud Storage instead of the container-local file path.
Service-specific runtime overlays
Some parts of the repo intentionally carry their own runtime contract. The US-facing API documentation in documents/us-api-v1.md defines purpose values, data-category scope, consent-scoped access tokens, and required headers separately from the main web deployment.
That separation matters because the repo includes flows that are not meant to share one universal configuration shape. The main frontend can be local-file backed, bucket backed, or backend merged depending on env vars, while the US API contract is governed by consent scope and auth headers rather than Compose placement.
Local Runtime Layer
documents/development.md
documents/development.md*
This file is the clearest operator-facing summary of local configuration. It shows the startup command that sources .env before Compose, the local account role overrides, and the feature flags that change what the frontend dashboard sees.
| Variable | Purpose |
|---|---|
ADMIN_EMAILS |
Comma-separated list of addresses that should receive the admin role. |
REALTOR_EMAILS |
Comma-separated list of reviewer accounts. |
DEFAULT_REALTOR_PASSWORD |
Overrides the shared reviewer password used by the preloaded test accounts. |
ENABLE_REMOTE_APPLICATIONS |
Enables frontend merging of remote applicants from the backend container. |
NEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONS |
Frontend-visible equivalent of the remote applicant toggle. |
APPLICATIONS_DATA_FILE |
Overrides the frontend submission storage path. |
SALTEDGE_* |
Environment variables mounted into the backend container for Salt Edge connectivity. |
The local guide also documents the Next.js 16 requirement and the containerized failure mode that appears when the frontend image is still running on Node 18. That makes Node versioning part of the runtime configuration, not just a package-level dependency.
platform/deployment/local/docker-compose.yml
platform/deployment/local/docker-compose.yml*
This file is the local execution graph for the repo. It is started explicitly from the root shell after .env is sourced, which means local runtime values are assembled at launch time rather than hidden inside a single image.
The local compose stack coexists with a separate HTTP routing layer in platform/deployment/local/Caddyfile. That split makes local ingress part of the repository’s runtime config, not just an implementation detail inside the application containers.
platform/deployment/local/Caddyfile
platform/deployment/local/Caddyfile*
The local Caddyfile is the local ingress companion to the Compose stack. It belongs to the development deployment folder rather than the application code, which keeps routing configuration next to the local runtime definition.
In practice, that means local HTTP behavior is configured alongside the container graph instead of being inherited from production routing or from the frontend itself.
Production Runtime Layer
platform/deployment/prod/docker-compose.yml
platform/deployment/prod/docker-compose.yml*
Production uses its own Compose definition. The deployment guide shows that the operator fetches the latest repo state on the VM, then brings the stack down, updates images, and starts it again from the production deployment directory.
That production runtime is paired with separate infra steps:
gcloud auth configure-docker us-central1-docker.pkg.devdocker-compose pulldocker-compose up -d --build
The deployment docs also show a schema synchronization step that is not part of the container rollout itself. platform/database/apply_schema.sh reuses the production Compose setup to execute platform/database/1_create_database.sql inside the running MySQL container.
documents/deployment.md
documents/deployment.md*
This guide captures the production-specific controls that are absent from the local workflow:
| Setting or step | Purpose |
|---|---|
| Fastly origin on top of GCLB | Production traffic is routed through Fastly before reaching the Google Cloud HTTPS Load Balancer. |
/api/* path routing |
API requests are routed to the API backend service. |
| Non-API routing | Browser traffic is routed to the frontend service. |
APPLICATIONS_DATA_GCS_BUCKET |
Enables bucket-backed application persistence in production. |
APPLICATIONS_DATA_GCS_OBJECT |
Optional object name override for the stored submissions file. |
MYSQL_USER and MYSQL_PASSWORD |
Used by apply_schema.sh when applying the current schema to an existing database. |
The guide also shows that production verification happens after deployment, not as part of the Compose file itself. That keeps the operational workflow separate from the service graph.
Frontend Runtime Layer
frontend/.env.production
frontend/.env.production*
This file is the production frontend’s explicit runtime overlay. The documented values are:
VITE_BACKEND_API_URL=https://app.joinlita.com
ALLOWED_ORIGINS=https://app.joinlita.com
These values show that the frontend is configured as a hosted application with a specific backend target and origin policy, rather than inheriting local defaults. The production deploy can also expose GCS-backed persistence variables for the application submission route when needed.
Frontend application storage behavior
The frontend route for /api/v1/applications is documented as a runtime merge of multiple sources:
- remote backend applicants, enabled only when
ENABLE_REMOTE_APPLICATIONSorNEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONSis set - local submissions stored in
data/applications.json - optional production storage in Google Cloud Storage through
APPLICATIONS_DATA_GCS_BUCKET
That means the same route can behave like a local file-backed service, a remote aggregator, or a production bucket-backed persistence layer depending on the environment.
Backend Runtime Layer
backend/src/main.py
backend/src/main.py*
The backend container has its own runtime default for CORS. ALLOWED_ORIGINS is read from the environment and split on commas, with a default value of http://localhost:3000.
That default matches the local frontend origin, while production overrides are supplied by the deployment environment. This is one of the few places where the backend itself exposes a runtime assumption instead of relying entirely on the deployment layer.
US Service Contract
documents/us-api-v1.md
documents/us-api-v1.md*
The US API contract is intentionally separate from the main app deployment surfaces. It defines a region-specific runtime model for consent, token scope, and request authorization.
| Contract element | Value |
|---|---|
| API version | v1 |
| Region | United States |
| Consent purpose values | RENTAL_SCREENING, LENDING_UNDERWRITING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, GENERAL_PERSONAL_FINANCE |
| Data categories | IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING |
| Partner auth headers | Authorization: Bearer <PARTNER_TOKEN>, X-Request-Id: <uuid> |
| Consent-scoped token header | Authorization: Bearer <ACCESS_TOKEN> |
This document makes the US service explicit about runtime expectations instead of inheriting them from the general web stack. It is a separate configuration domain with its own request shape, auth model, and consent rules.
Runtime Flow
Local application submission and dashboard merge
sequenceDiagram
participant Dev as Developer
participant Shell as Shell Env
participant Compose as Local Compose
participant Frontend as Frontend
participant Backend as Backend
participant File as Local Data File
participant Browser as Browser
Dev->>Shell: source .env
Dev->>Compose: start local stack
Compose->>Frontend: pass runtime vars
Compose->>Backend: pass runtime vars
Browser->>Frontend: open dashboard or submit application
alt Remote applicants enabled
Frontend->>Backend: fetch remote applicants
Backend-->>Frontend: remote applicant list
else Remote applicants disabled
Frontend-->>Frontend: skip remote fetch
end
Frontend->>File: read or append local submissions
Frontend-->>Browser: merged application data
Browser->>Browser: render dashboard
Production rollout and schema application
sequenceDiagram
participant Operator as Operator
participant VM as Compute Engine VM
participant Repo as Deployment Folder
participant Compose as Production Compose
participant Schema as Schema Helper
participant Registry as Artifact Registry
participant DB as MySQL
Operator->>VM: SSH into instance
VM->>Repo: git fetch and rebase
Repo->>Compose: docker-compose down
Repo->>Registry: authenticate for image pull
Repo->>Compose: docker-compose pull
Repo->>Compose: docker-compose up -d --build
Operator->>Schema: run apply_schema.sh with MYSQL_USER and MYSQL_PASSWORD
Schema->>Compose: reuse production compose
Compose->>DB: execute 1_create_database.sql
DB-->>Compose: schema applied
Error Handling and Fallbacks
Configuration in this repo is defensive rather than assumed.
- The frontend applicant routes return a 500 when neither
NEXT_PUBLIC_BACKEND_API_URLnorBACKEND_API_URLcan be resolved. - The local frontend route falls back to stored submissions when the remote backend data path is disabled.
- The production deployment keeps schema application separate from container startup so missing MySQL tables can be repaired without rebuilding the stack.
- The backend CORS policy falls back to
http://localhost:3000ifALLOWED_ORIGINSis not set. - The US API documentation defines its own rejected-purpose and out-of-scope categories so service-specific requests do not silently inherit unsupported behavior.
Dependencies
The configuration surfaces in this section depend on the following external systems and tools:
- Docker and Docker Compose
- Caddy for local HTTP routing
- Fastly and Google Cloud HTTPS Load Balancer for production ingress
- Google Cloud Artifact Registry for image pulls
- Google Cloud Storage for optional frontend submission persistence
- MySQL for application schema and production data
- Google Cloud SDK for SSH and deployment commands
- Next.js frontend runtime env handling
- FastAPI backend runtime env handling
Testing Considerations
Useful checks for this configuration layer:
- Start local stack with
set -a && source .env && set +abeforedocker compose -f platform/deployment/local/docker-compose.yml up -d --build. - Confirm the frontend sees real application data with
curl http://localhost:3000/api/v1/applications. - Verify remote applicant aggregation by exporting
ENABLE_REMOTE_APPLICATIONS=trueorNEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONS=true. - Inspect container env values with
docker compose -f platform/deployment/local/docker-compose.yml exec frontend env | grep BACKEND_API_URL. - Verify backend access to Salt Edge runtime values with
docker compose -f platform/deployment/local/docker-compose.yml exec backend env | grep SALTEDGE. - Run
platform/database/apply_schema.shafter deploying new schema-dependent features to a long-lived production database. - Confirm production frontend env values include the hosted backend URL and origin policy before rollout.
- Validate US API requests against the documented purpose and data-category scopes before wiring them into any client integration.
Key Classes Reference
| Class | Responsibility |
|---|---|
documents/development.md |
Local setup guidance, environment variable surfaces, and stack startup instructions. |
platform/deployment/local/docker-compose.yml |
Local container graph for developer runtime. |
platform/deployment/local/Caddyfile |
Local routing and ingress configuration. |
platform/deployment/prod/docker-compose.yml |
Production container graph for Compute Engine deployment. |
frontend/.env.production |
Production frontend environment values. |
backend/src/main.py |
Backend runtime defaults, including CORS origin handling. |
documents/us-api-v1.md |
US-specific consent and authorization contract. |
documents/deployment.md |
Production rollout, schema application, and verification workflow. |