# tg11-org/ff-core architecture

> Architecture diagram of the GitHub repository tg11-org/ff-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tg11-org/ff-core
- Repository: https://github.com/tg11-org/ff-core

## Overview

Core is the Forge Foundation control-plane API: callers authenticate, submit instance operations, and receive persisted state plus queued work. Its runtime separates HTTP routes, service decisions, SQLAlchemy-backed business state, scheduling, and worker-facing job updates. The README documents the wider Pulse → Fabric → Proxmox execution chain; implementation details for that chain are not shown in the sampled code, so those links are documented rather than inferred from imports.

Main entry points: [`app/db/models.py`](https://github.com/tg11-org/ff-core/blob/master/app/db/models.py) (Core domain models), [`app/api/routes/instances.py`](https://github.com/tg11-org/ff-core/blob/master/app/api/routes/instances.py) (Instance routes), [`app/api/routes/internal.py`](https://github.com/tg11-org/ff-core/blob/master/app/api/routes/internal.py) (Worker routes), [`app/db/session.py`](https://github.com/tg11-org/ff-core/blob/master/app/db/session.py) (DB sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_main["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_instance_routes["Instance routes<br/>[instances.py]"]
  node_internal_routes["Worker routes<br/>[internal.py]"]
  node_auth_deps["Auth dependencies<br/>[dependencies.py]"]
  node_auth_schemas["Auth contracts<br/>[auth.py]"]
  node_instance_schemas["Instance contracts<br/>[instances.py]"]
  node_common_schemas["Common contracts<br/>[common.py]"]
  node_internal_schemas["Internal contracts<br/>[internal.py]"]
end

subgraph group_domain["Control-plane services"]
  node_auth_service["Auth service<br/>[auth.py]"]
  node_instance_service["Instance service<br/>[instances.py]"]
  node_scheduler["Capacity scheduler<br/>[scheduler.py]"]
  node_audit["Audit service<br/>[audit.py]"]
  node_security["Token security<br/>[security.py]"]
  node_config["Service settings<br/>[config.py]"]
end

subgraph group_state["Business state"]
  node_db_session["DB sessions<br/>[session.py]"]
  node_models["Core domain models<br/>[models.py]"]
  node_database[("PostgreSQL state")]
end

subgraph group_execution["Async execution"]
  node_job_service["Job producer<br/>[jobs.py]"]
end

node_forge(("Forge clients"))
node_pulse["Pulse worker"]
node_fabric["Fabric adapter<br/>[fabric.py]"]
node_proxmox["Proxmox"]

node_forge -->|"calls JSON API"| node_main
node_main -->|"registers router"| node_auth_routes
node_main -->|"registers router"| node_instance_routes
node_main -->|"registers router"| node_internal_routes
node_auth_routes -->|"delegates to"| node_auth_service
node_auth_routes -->|"validates with"| node_auth_schemas
node_auth_routes -->|"opens session"| node_db_session
node_auth_service -->|"queries and creates"| node_models
node_auth_service -->|"hashes and signs"| node_security
node_auth_deps -->|"verifies token"| node_security
node_auth_deps -->|"loads user"| node_auth_service
node_auth_deps -->|"opens session"| node_db_session
node_instance_routes -->|"requires user"| node_auth_deps
node_instance_routes -->|"delegates operations"| node_instance_service
node_instance_routes -->|"uses contracts"| node_instance_schemas
node_instance_routes -->|"returns pagination"| node_common_schemas
node_instance_service -->|"selects capacity"| node_scheduler
node_instance_service -->|"creates jobs"| node_job_service
node_instance_service -->|"uses domain records"| node_models
node_scheduler -->|"reads node capacity"| node_models
node_job_service -->|"persists job records"| node_models
node_job_service -->|"reads queue settings"| node_config
node_db_session -->|"reads database URL"| node_config
node_db_session -->|"connects"| node_database
node_audit -->|"records audit events"| node_models
node_internal_routes -->|"reads and updates"| node_models
node_internal_routes -->|"opens session"| node_db_session
node_internal_routes -->|"returns worker data"| node_instance_schemas
node_pulse -.->|"consumes queued work"| node_job_service
node_pulse -.->|"reports job state"| node_internal_routes
node_pulse -.->|"dispatches operations"| node_fabric
node_fabric -.->|"adapts compute calls"| node_proxmox

click node_main "https://github.com/tg11-org/ff-core/blob/master/app/main.py"
click node_auth_routes "https://github.com/tg11-org/ff-core/blob/master/app/api/routes/auth.py"
click node_instance_routes "https://github.com/tg11-org/ff-core/blob/master/app/api/routes/instances.py"
click node_internal_routes "https://github.com/tg11-org/ff-core/blob/master/app/api/routes/internal.py"
click node_auth_deps "https://github.com/tg11-org/ff-core/blob/master/app/api/dependencies.py"
click node_auth_schemas "https://github.com/tg11-org/ff-core/blob/master/app/schemas/auth.py"
click node_instance_schemas "https://github.com/tg11-org/ff-core/blob/master/app/schemas/instances.py"
click node_common_schemas "https://github.com/tg11-org/ff-core/blob/master/app/schemas/common.py"
click node_internal_schemas "https://github.com/tg11-org/ff-core/blob/master/app/schemas/internal.py"
click node_auth_service "https://github.com/tg11-org/ff-core/blob/master/app/services/auth.py"
click node_instance_service "https://github.com/tg11-org/ff-core/blob/master/app/services/instances.py"
click node_scheduler "https://github.com/tg11-org/ff-core/blob/master/app/services/scheduler.py"
click node_audit "https://github.com/tg11-org/ff-core/blob/master/app/services/audit.py"
click node_security "https://github.com/tg11-org/ff-core/blob/master/app/core/security.py"
click node_config "https://github.com/tg11-org/ff-core/blob/master/app/core/config.py"
click node_db_session "https://github.com/tg11-org/ff-core/blob/master/app/db/session.py"
click node_models "https://github.com/tg11-org/ff-core/blob/master/app/db/models.py"
click node_job_service "https://github.com/tg11-org/ff-core/blob/master/app/services/jobs.py"
click node_fabric "https://github.com/tg11-org/ff-core/blob/master/app/services/fabric.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_auth_routes,node_instance_routes,node_internal_routes,node_auth_deps,node_auth_schemas,node_instance_schemas,node_common_schemas,node_internal_schemas,node_forge toneBlue
class node_auth_service,node_instance_service,node_scheduler,node_audit,node_security,node_config toneAmber
class node_db_session,node_models,node_database toneMint
class node_job_service,node_pulse toneRose
class node_fabric toneTeal
class node_proxmox toneIndigo
```

## Components

### API and identity

- [FastAPI app](https://github.com/tg11-org/ff-core/blob/master/app/main.py): `app/main.py`
- [Auth routes](https://github.com/tg11-org/ff-core/blob/master/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Instance routes](https://github.com/tg11-org/ff-core/blob/master/app/api/routes/instances.py): `app/api/routes/instances.py`
- [Worker routes](https://github.com/tg11-org/ff-core/blob/master/app/api/routes/internal.py): `app/api/routes/internal.py`
- [Auth dependencies](https://github.com/tg11-org/ff-core/blob/master/app/api/dependencies.py): `app/api/dependencies.py`
- [Auth contracts](https://github.com/tg11-org/ff-core/blob/master/app/schemas/auth.py): `app/schemas/auth.py`
- [Instance contracts](https://github.com/tg11-org/ff-core/blob/master/app/schemas/instances.py): `app/schemas/instances.py`
- [Common contracts](https://github.com/tg11-org/ff-core/blob/master/app/schemas/common.py): `app/schemas/common.py`
- [Internal contracts](https://github.com/tg11-org/ff-core/blob/master/app/schemas/internal.py): `app/schemas/internal.py`

### Control-plane services

- [Auth service](https://github.com/tg11-org/ff-core/blob/master/app/services/auth.py): `app/services/auth.py`
- [Instance service](https://github.com/tg11-org/ff-core/blob/master/app/services/instances.py): `app/services/instances.py`
- [Capacity scheduler](https://github.com/tg11-org/ff-core/blob/master/app/services/scheduler.py): `app/services/scheduler.py`
- [Audit service](https://github.com/tg11-org/ff-core/blob/master/app/services/audit.py): `app/services/audit.py`
- [Token security](https://github.com/tg11-org/ff-core/blob/master/app/core/security.py): `app/core/security.py`
- [Service settings](https://github.com/tg11-org/ff-core/blob/master/app/core/config.py): `app/core/config.py`

### Business state

- [DB sessions](https://github.com/tg11-org/ff-core/blob/master/app/db/session.py): `app/db/session.py`
- [Core domain models](https://github.com/tg11-org/ff-core/blob/master/app/db/models.py): `app/db/models.py`
- **PostgreSQL state**

### Async execution

- [Job producer](https://github.com/tg11-org/ff-core/blob/master/app/services/jobs.py): `app/services/jobs.py`

### Other components

- **Forge clients**
- **Pulse worker**
- [Fabric adapter](https://github.com/tg11-org/ff-core/blob/master/app/services/fabric.py): `app/services/fabric.py`
- **Proxmox**

## Connections

- Forge clients → FastAPI app: calls JSON API (evidence: `README.md`)
- FastAPI app → Auth routes: registers router (evidence: `app/main.py`)
- FastAPI app → Instance routes: registers router (evidence: `app/main.py`)
- FastAPI app → Worker routes: registers router (evidence: `app/main.py`)
- Auth routes → Auth service: delegates to (evidence: `app/api/routes/auth.py`)
- Auth routes → Auth contracts: validates with (evidence: `app/api/routes/auth.py`)
- Auth routes → DB sessions: opens session (evidence: `app/api/routes/auth.py`)
- Auth service → Core domain models: queries and creates (evidence: `app/services/auth.py`)
- Auth service → Token security: hashes and signs (evidence: `app/services/auth.py`)
- Auth dependencies → Token security: verifies token (evidence: `app/api/dependencies.py`)
- Auth dependencies → Auth service: loads user (evidence: `app/api/dependencies.py`)
- Auth dependencies → DB sessions: opens session (evidence: `app/api/dependencies.py`)
- Instance routes → Auth dependencies: requires user (evidence: `app/api/routes/instances.py`)
- Instance routes → Instance service: delegates operations (evidence: `app/api/routes/instances.py`)
- Instance routes → Instance contracts: uses contracts (evidence: `app/api/routes/instances.py`)
- Instance routes → Common contracts: returns pagination (evidence: `app/api/routes/instances.py`)
- Instance service → Capacity scheduler: selects capacity (evidence: `app/services/instances.py`)
- Instance service → Job producer: creates jobs (evidence: `app/services/instances.py`)
- Instance service → Core domain models: uses domain records (evidence: `app/services/instances.py`)
- Capacity scheduler → Core domain models: reads node capacity (evidence: `app/services/scheduler.py`)
- Job producer → Core domain models: persists job records (evidence: `app/services/jobs.py`)
- Job producer → Service settings: reads queue settings (evidence: `app/services/jobs.py`)
- DB sessions → Service settings: reads database URL (evidence: `app/db/session.py`)
- DB sessions → PostgreSQL state: connects (evidence: `app/db/session.py`)
- Audit service → Core domain models: records audit events (evidence: `app/services/audit.py`)
- Worker routes → Core domain models: reads and updates (evidence: `app/api/routes/internal.py`)
- Worker routes → DB sessions: opens session (evidence: `app/api/routes/internal.py`)
- Worker routes → Instance contracts: returns worker data (evidence: `app/api/routes/internal.py`)
- Pulse worker → Job producer: consumes queued work (evidence: `README.md`)
- Pulse worker → Worker routes: reports job state (evidence: `README.md`)
- Pulse worker → Fabric adapter: dispatches operations (evidence: `README.md`)
- Fabric adapter → Proxmox: adapts compute calls (evidence: `README.md`)