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 .env model.

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.dev
  • docker-compose pull
  • docker-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_APPLICATIONS or NEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONS is 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_URL nor BACKEND_API_URL can 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:3000 if ALLOWED_ORIGINS is 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 +a before docker 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=true or NEXT_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.sh after 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.