Deployment & Hosting
Relevant source files
The following files were used as context for generating this wiki page:
The Financial Asset Relationship Database employs a dual-path deployment strategy. The production environment utilizes a FastAPI backend and a Next.js frontend, while non-production environments use a Gradio UI for internal testing and demonstrations. The system supports various hosting platforms, including Vercel for cloud production, Docker for containerized environments, and local development setups.
Sources: ARCHITECTURE.md:3-9, AGENTS.md:14-17, README.md:213-216
Production Architecture and Vercel Hosting
The production environment separates the application into a TypeScript/React frontend (Next.js) and a Python backend (FastAPI). Vercel hosts this architecture using a combination of Edge functions for static assets and Serverless Functions for the API layer.
Deployment Workflow
Vercel manages deployments through a Git-integrated workflow or via the Vercel CLI. The vercel.json file configures the routing logic between the frontend and the backend API.
This diagram illustrates the request routing logic where API calls are directed to serverless functions while UI assets are served from the edge.
Sources: ARCHITECTURE.md:126-146, vercel.json:1-12, INTEGRATION_SUMMARY.md:105-132
Configuration (vercel.json)
The vercel.json file defines the build process and routing. It utilizes the @vercel/python runtime for the api/main.py entry point and specifies a standard npm run build for the frontend.
| Key | Value/Description |
|---|---|
| Build Runtime | @vercel/python (for API) |
| Max Lambda Size | 50mb (Standard) |
| API Route Pattern | /api/(.*) redirects to api/main.py |
| Node.js Version | 18+ |
Sources: vercel.json:1-12, VERCEL_DEPLOYMENT_CHECKLIST.md:215-225, README.md:27-29
Containerized Deployment (Docker)
The project provides Docker Compose configurations for both general and production-specific containerized deployments. These configurations orchestrate the backend service and the non-production Gradio UI.
Service Orchestration
The system defines services for the application, ensuring environment variables and volumes are correctly mapped for persistence.
This diagram shows the relationship between the application container and the persistence layer within a Docker network.
Sources: docker-compose.yml:1-15, docker-compose.production.yml:1-20
Docker Environments
- Standard (
docker-compose.yml): Uses default environment files (.env) and maps host port 7860 to container port 7860 for the Gradio UI. - Production (
docker-compose.production.yml): Implementsrestart: unless-stoppedpolicies and utilizes a production-specific environment file (.env.production).
Sources: docker-compose.yml:5-15, docker-compose.production.yml:5-20
Environment Configuration
Configuration is centralized via src/config/settings.py. Production environments require specific environment variables to manage authentication, database connectivity, and data fetching behavior.
Critical Environment Variables
| Variable | Environment | Description |
|---|---|---|
DATABASE_URL | All | Connection string (SQLite for dev, PostgreSQL for prod). |
SECRET_KEY | Production | JWT signing secret for backend authentication. |
ADMIN_USERNAME | Production | Seed credential for the initial admin user. |
ADMIN_PASSWORD | Production | Seed credential for the initial admin user. |
NEXT_PUBLIC_API_URL | Frontend | The base URL of the FastAPI backend. |
ASSET_GRAPH_DATABASE_URL | Staging/Prod | Required for durable graph-persistence promotion. |
Sources: VERCEL_DEPLOYMENT_CHECKLIST.md:112-132, README.md:38-45, AGENTS.md:52-62
Database Resolution
The API employs a custom resolver for SQLite paths. Standard SQLAlchemy paths like sqlite:///./dev.db may fail in cloud environments due to write permissions. Use the format sqlite:dev.db for repository-relative paths or absolute paths for cloud storage.
Sources: README.md:143-160, AGENTS.md:219-228
Health and Readiness Monitoring
The system includes mechanisms to verify the status of hosted deployments, specifically targeting the /api/health and /api/health/detailed endpoints.
Hosted Readiness Script
The scripts/check_hosted_readiness.py utility performs smoke checks against deployed instances. It validates:
- Liveness: Basic connectivity to the
/api/healthendpoint. - Readiness: Detailed component status from
/api/health/detailed. - Persistence: Optional verification that the graph is loaded from a persisted source rather than sample data.
- Data Integrity: Optional verification that asset queries return at least one record.
This sequence shows the validation flow used to confirm a successful promotion to staging or production.
Sources: scripts/check_hosted_readiness.py:1-45, VERCEL_DEPLOYMENT_CHECKLIST.md:164-185, README.md:112-124
Conclusion
Deployment and hosting for the Financial Asset Relationship Database are structured to support high-availability production via Vercel and FastAPI, while maintaining flexible local and containerized options for development. Adherence to the centralized configuration and mandatory readiness checks ensures that promotions to production maintain durable persistence and system integrity.
Sources: VERCEL_DEPLOYMENT_CHECKLIST.md:358-370, AGENTS.md:200-210