Skip to content
InfraKitchen
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  1. 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
  2. Service Layer (service.py)

    • Business logic
    • Orchestration between modules
    • Transaction management, publishing task/event messages
  3. CRUD Layer (crud.py)

    • Database operations
    • Query building
    • Data access patterns
  4. Task Layer (task.py)

    • Asynchronous operations executed by the worker
    • Long-running processes (provisioning, destroying, dry runs)
    • Pipeline orchestration per entity
  5. Model Layer (model.py)

    • SQLAlchemy ORM models (extending BaseEntity / BaseRevision)
    • An internal Pydantic DTO used between the service and task layers
  6. 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.

Last updated on