Contributing
Conventions and workflows for developers contributing code to InfraKitchen.
Follow these conventions when a change touches the areas below — they keep the codebase consistent and make reviews faster.
Codebase Structure
server/src/
├── application/ # Application layer, one folder per domain
│ ├── resources/ # crud.py · service.py · model.py · schema.py · task.py
│ ├── executors/ # same structure
│ ├── templates/ # ...
│ ├── integrations/
│ ├── workspaces/
│ ├── workflows/
│ ├── views/ # Router mounting (auth + GraphQL)
│ ├── use_cases/ # Multi-service orchestration
│ └── ...
├── graphql_api/ # GraphQL API (Strawberry)
│ ├── context.py # Auth context & DB session
│ ├── endpoint.py # GraphQLRouter mount
│ ├── helpers.py # Permissions, field optimization
│ ├── schema.py # Merged query schema
│ └── modules/ # Per-entity types, converters, queries, mutations, subscriptions
├── core/ # Core utilities and shared domains
│ ├── adapters/ # External service adapters
│ ├── config.py # Configuration
│ ├── database.py # Database connection
│ ├── base_models.py # Base / BaseEntity / BaseModel / MessageModel
│ ├── errors.py # Custom exceptions
│ └── ...
├── mcp_server/ # MCP server
├── worker.py # Task worker entrypoint (claims tasks from the Postgres task queue)
├── scheduler.py # Scheduler entrypoint (APScheduler)
├── app.py # FastAPI app entrypoint
└── fixtures/ # Demo data
Code Layers
-
GraphQL Layer (
graphql_api/)- Strawberry GraphQL schema and types
- Queries, mutations, and subscriptions per entity
- Bearer token authentication via permission classes
- See GraphQL API for usage details
-
Service Layer (
service.py)- Business logic
- Orchestration between modules
- Transaction management, publishing task/event messages
-
CRUD Layer (
crud.py)- Database operations
- Query building
- Data access patterns
-
Task Layer (
task.py)- Asynchronous operations executed by the worker
- Long-running processes (provisioning, destroying, dry runs)
- Pipeline orchestration per entity
-
Model Layer (
model.py)- SQLAlchemy ORM models (extending
BaseEntity/BaseRevision) - An internal Pydantic DTO used between the service and task layers
- SQLAlchemy ORM models (extending
-
Schema Layer (
schema.py)- Pydantic request/response schemas (create/update/response types) used by the GraphQL and REST layers
Database Migrations
InfraKitchen’s backend uses SQLAlchemy as its ORM to define database models, and Alembic to manage schema migrations.
When adding or changing a SQLAlchemy model, generate a migration with Alembic autogenerate. Do not write migration files by hand, and do not copy/rename an existing migration as a shortcut — autogenerate keeps the migration history consistent with the models.
Steps:
Make the model changes
Make the model changes in server/src/.
Generate the migration
From the server/ directory, run:
cd server
alembic -c src/alembic.ini revision --autogenerate -m "<describe the change>"If the virtual environment isn’t activated, prefix with uv run:
uv run alembic -c src/alembic.ini revision --autogenerate -m "<describe the change>"Review the generated migration
Open the generated file in server/src/alembic/versions/ and review it carefully. Autogenerate is reliable for most changes, but it can miss or misdetect things like column/table renames, enum value changes, or server-side defaults — fix the generated script by hand if needed before moving on.
Commit
Commit the migration file in the same pull request as the model change it corresponds to — do not split them across PRs.