How tg11-org/ff-core works
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: models.py Core domain models · instances.py Instance routes · internal.py Worker routes · session.py DB sessions
Components 23
API and identity
- FastAPI app
app/main.py - Auth routes
app/api/routes/auth.py - Instance routes
app/api/routes/instances.py - Worker routes
app/api/routes/internal.py - Auth dependencies
app/api/dependencies.py - Auth contracts
app/schemas/auth.py - Instance contracts
app/schemas/instances.py - Common contracts
app/schemas/common.py - Internal contracts
app/schemas/internal.py
Control-plane services
- Auth service
app/services/auth.py - Instance service
app/services/instances.py - Capacity scheduler
app/services/scheduler.py - Audit service
app/services/audit.py - Token security
app/core/security.py - Service settings
app/core/config.py
Business state
- DB sessions
app/db/session.py - Core domain models
app/db/models.py - PostgreSQL state
Async execution
- Job producer
app/services/jobs.py
Other components
- Forge clients
- Pulse worker
- Fabric adapter
app/services/fabric.py - Proxmox
Connections 32
- Forge clients → FastAPI app: calls JSON API
README.md - FastAPI app → Auth routes: registers router
app/main.py - FastAPI app → Instance routes: registers router
app/main.py - FastAPI app → Worker routes: registers router
app/main.py - Auth routes → Auth service: delegates to
app/api/routes/auth.py - Auth routes → Auth contracts: validates with
app/api/routes/auth.py - Auth routes → DB sessions: opens session
app/api/routes/auth.py - Auth service → Core domain models: queries and creates
app/services/auth.py - Auth service → Token security: hashes and signs
app/services/auth.py - Auth dependencies → Token security: verifies token
app/api/dependencies.py - Auth dependencies → Auth service: loads user
app/api/dependencies.py - Auth dependencies → DB sessions: opens session
app/api/dependencies.py - Instance routes → Auth dependencies: requires user
app/api/routes/instances.py - Instance routes → Instance service: delegates operations
app/api/routes/instances.py - Instance routes → Instance contracts: uses contracts
app/api/routes/instances.py - Instance routes → Common contracts: returns pagination
app/api/routes/instances.py - Instance service → Capacity scheduler: selects capacity
app/services/instances.py - Instance service → Job producer: creates jobs
app/services/instances.py - Instance service → Core domain models: uses domain records
app/services/instances.py - Capacity scheduler → Core domain models: reads node capacity
app/services/scheduler.py - Job producer → Core domain models: persists job records
app/services/jobs.py - Job producer → Service settings: reads queue settings
app/services/jobs.py - DB sessions → Service settings: reads database URL
app/db/session.py - DB sessions → PostgreSQL state: connects
app/db/session.py - Audit service → Core domain models: records audit events
app/services/audit.py - Worker routes → Core domain models: reads and updates
app/api/routes/internal.py - Worker routes → DB sessions: opens session
app/api/routes/internal.py - Worker routes → Instance contracts: returns worker data
app/api/routes/internal.py - Pulse worker → Job producer: consumes queued work
README.md - Pulse worker → Worker routes: reports job state
README.md - Pulse worker → Fabric adapter: dispatches operations
README.md - Fabric adapter → Proxmox: adapts compute calls
README.md