Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Getting Started & Local Setup defines the procedures and environmental requirements for deploying the Financial Asset Relationship Database in a local development environment. This guide covers the installation of the core Python backend, the Next.js frontend, and the optional Gradio demonstration interface.
The project utilizes a dual-architecture approach. The Production Architecture consists of a FastAPI backend and a Next.js frontend, while the Non-Production Architecture uses a Gradio UI for rapid testing and demonstrations. Sources: ARCHITECTURE.md:3-8, AGENTS.md:12-16
Prerequisites
Before starting the setup, you must ensure your system meets the following software requirements:
- Python: Version 3.10 or higher (3.12 is recommended). Sources: CONTRIBUTING.md:21, AGENTS.md:200
- Node.js: Version 18 or higher. Sources: QUICK_START.md:14
- Git: Required for repository management and cloning. Sources: CONTRIBUTING.md:22
- Virtual Environment Tool:
venv,virtualenv, orconda. Sources: CONTRIBUTING.md:23
Installation and Environment Setup
Local setup involves cloning the repository and configuring a Python virtual environment to isolate dependencies.
1. Repository Acquisition
Clone the repository and move into the project root:
git clone https://github.com/YOUR_USERNAME/financial-asset-relationship-db.git
cd financial-asset-relationship-db
Sources: CONTRIBUTING.md:30-31
2. Python Environment Configuration
Create and activate a virtual environment to manage backend dependencies:
| Operating System | Command |
|---|---|
| Windows (PowerShell) | python -m venv .venv then .\.venv\Scripts\Activate.ps1 |
| Windows (CMD) | python -m venv .venv then .venv\Scripts\activate.bat |
| macOS / Linux | python -m venv .venv then source .venv/bin/activate |
Sources: CONTRIBUTING.md:41-58
3. Dependency Installation
The project provides multiple installation paths based on your role:
- Runtime only:
pip install -r requirements.txt - Core development:
pip install -e ".[dev]" - Full contributor tooling:
pip install -r requirements.txt -r requirements-dev.txt
Sources: CONTRIBUTING.md:65-73
Local Development Execution
The project supports both automated and manual execution of the service stack.
Automated Startup
Automated scripts handle the concurrent execution of the FastAPI backend and Next.js frontend.
- Linux/macOS: Run
./run-dev.sh. Sources: run-dev.sh:1, QUICK_START.md:21-25 - Windows: Run
run-dev.bat. Sources: run-dev.bat:1, QUICK_START.md:28-30
Service Architecture Flow
The following diagram illustrates the startup sequence and interaction between components during local development.
The startup process initializes the environment, launches the backend to serve data via REST API, and starts the frontend to visualize the relationships. Sources: ARCHITECTURE.md:12-65, QUICK_START.md:34-40
Configuration and Environment Variables
The system relies on specific environment variables for authentication and database connectivity. These are centralized via src/config/settings.py.
Essential Backend Variables
| Variable | Description | Example/Default |
|---|---|---|
DATABASE_URL | SQLite connection string | sqlite:dev.db |
SECRET_KEY | JWT signing key | openssl rand -hex 32 |
ADMIN_USERNAME | Default admin username | admin |
ADMIN_PASSWORD | Default admin password | user-defined |
Sources: AGENTS.md:34-45, AGENTS.md:210-215
Essential Frontend Variables
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_API_URL | Backend API entry point | http://localhost:8000 |
FRONTEND_PORT | Next.js listening port | 3000 |
Sources: QUICK_START.md:6-10, AGENTS.md:58-61
Development Workflow Commands
Developers should use the provided Makefile or manual commands to maintain code quality and run tests.
Quality Control Commands
- Linting:
make lintorflake8 src//pylint src/. Sources: SUMMARY.md:104, AGENTS.md:103-104 - Formatting:
make formatorblack src//isort src/. Sources: SUMMARY.md:105, AGENTS.md:105-106 - Type Checking:
make type-checkormypy src/. Sources: SUMMARY.md:107, AGENTS.md:107
Test Execution
- Run all tests:
pytest. Sources: CONTRIBUTING.md:154, AGENTS.md:82 - Frontend tests:
cd frontend && npm test. Sources: AGENTS.md:94-96 - Coverage report:
pytest --cov=src. Sources: CONTRIBUTING.md:160, AGENTS.md:91
Summary
Setting up the Financial Asset Relationship Database locally requires configuring a Python 3.10+ environment and a Node.js 18+ environment. You can use the run-dev scripts to launch the integrated FastAPI and Next.js services. Developers must configure basic environment variables for database paths and security keys to enable full functionality of the asset graph and 3D visualization components. Sources: QUICK_START.md:32-40, AGENTS.md:12-25