Developer Quick Start¶

Getting a full Golden Age Hub development environment running from a clean checkout takes about five minutes. This guide walks you through it.

1. Clone and Install¶

Start by cloning the repository and installing the development toolchain:

git clone https://github.com/goldenagehub/goldenage-hub.git
cd goldenage-hub
make install-dev

make install-dev handles the uv virtual environment, pins the Python dependencies, and validates that the Docker daemon is reachable.

2. Bootstrap the Full Stack¶

A single command brings up every service — the API gateway, Celery pipeline worker, TimescaleDB, Redis, and OPA policy engine:

make setup-all

This is the canonical development command. Under the hood it builds the Docker images, starts the containers, waits for the gateway's health check to pass, and seeds the database with mock patient and device records. If you only want the containers (without the seed step):

make dev-up

3. Access the Running Services¶

Once the stack is up, the following endpoints are available:

Production Environment (American Cloud)¶

The production environment is deployed on secure, U.S.-sovereign Kubernetes clusters on American Cloud.

To start the frontend applications (in separate terminals) for local development:

make dashboard-up            # Main caregiver dashboard on :3000
make simulator-frontend-up   # Simulator control panel on :3003

Frontend Dashboard Setup & Development¶

The main caregiver dashboard is a React + Vite application. It connects to the FastAPI backend API to display real-time events, metrics, patient details, and device status.

Manual Setup (Without Make/Docker)¶

If you prefer to run the frontend outside of Docker (e.g., for faster hot reloading or debugging): 1. Navigate and Install:

cd frontend/dashboard
npm install

VITE_API_BASE_URL=http://localhost:8000/api/v1

npm run dev

Production Build¶

To build the frontend for production deployment:

cd frontend/dashboard
npm run build

npm run preview

Development Guidelines¶

• Adding New Pages: Create a new page component in src/pages/, register its path/route in src/App.tsx, and add a navigation link to the layout in src/components/Layout.tsx.
• Theming & Styling: Theme colors and global styles are defined in src/index.css. Components use Tailwind-like utility classes.
• API Integration: All service calls are routed through src/services/api.ts. Types are located in src/types/api.ts.

Frontend Troubleshooting¶

• CORS Errors: Ensure the backend gateway service is configured to allow origins from http://localhost:3000.
• Connection Failures: Verify that VITE_API_BASE_URL points to the correct running backend instance.
• No Data / Empty States: If the dashboard runs but shows no entries, populate the database with mock records using the generator CLI or API endpoint:

  curl -X POST http://localhost:8000/api/v1/mock/generate-data
  

4. Run the Test Suite¶

The test suite covers event ingestion, cryptographic signature verification, ledger operations, security controls, and end-to-end integration. All 90 tests pass against the live development stack:

make test                    # Full suite
make test-verbose            # With per-test output
make test-coverage           # With HTML coverage report

You can also run targeted test files directly:

cd backend
uv run pytest tests/test_events.py -v         # Event ingestion
uv run pytest tests/test_security.py -v       # Ed25519 signatures & replay protection
uv run pytest tests/test_integration.py -v    # End-to-end integration
uv run pytest tests/test_ledger.py -v         # Merkle tree & ledger verification

5. Database & Migration Operations¶

make migrate               # Apply pending Alembic migrations
make migrate-downgrade     # Roll back one revision
make db-reset              # Wipe and re-seed the database

6. Code Quality¶

The project enforces strict formatting, linting, and type-checking rules in CI. Run them locally before pushing:

make format        # Black + isort formatting
make lint          # Ruff linting
make type-check    # mypy type validation

7. Version & Release Management¶

make release-patch    # Bump patch version (0.x.Y)
make release-minor    # Bump minor version (0.X.0)
make release-major    # Bump major version (X.0.0)

Each release target updates pyproject.toml, creates a git tag, and generates a changelog entry.

Project Structure¶

goldenage-hub/
├── backend/
│   ├── services/
│   │   ├── gateway/       # FastAPI gateway — Ed25519 validation, rate limiting (port 8000)
│   │   └── pipeline/      # Celery event processing worker (port 8001)
│   ├── tests/             # Full test suite (90 tests)
│   └── pyproject.toml     # uv dependency manifest
├── frontend/
│   ├── dashboard/         # React + TS caregiver dashboard (port 3000)
│   └── simulator-dashboard/  # Simulator control panel (port 3003)
├── infra/
│   └── docker-compose.yml # Development service definitions
├── docs/                  # This documentation
├── models/                # Edge ML model cards and training configs
├── firmware/              # Companion Patch BLE/NFC protocol specs
└── Makefile               # Root development commands

Troubleshooting¶

Services won't start — Check the Docker daemon is running, then inspect logs:

docker-compose ps
make logs

Tests fail on a clean machine — Confirm the gateway health check passes before running tests. The test suite requires the full stack to be up:

curl http://localhost:8000/health
make setup-all  # if not already running

Database connectivity errors — Reset the database and re-seed:

make db-reset
make migrate

Further Reading¶

• Architecture Overview — Service topology, data flow, and component design
• API Specifications — Complete endpoint reference including the WebSocket alerts channel
• Development Guide — Git workflow, code style conventions, and CI/CD pipeline details
• Testing Guide — Database isolation, async test patterns, and coverage targets