Repository navigation
static typing
Static types make the architectural boundaries executable. They define what crosses a port, API, message or frontend boundary and give CI a way to reject incompatible changes.
The root pyproject.toml configures Python 3.14 and strict mypy settings:
- Strict mode is enabled.
- Untyped and incomplete function definitions are rejected.
- Implicit optional values are rejected.
- Unused ignores and redundant casts are reported.
- Missing type information is ignored only for listed signal-processing and infrastructure libraries.
The current just check-types recipe runs strict mypy against model/gts and TypeScript against model/video. The configuration is broader than that current command scope, so other Python packages still rely on Ruff, tests and local type checking until the gate expands.
Pyright has a Python 3.14 project setting, but it is not the primary CI type gate.
Core domain entities are typed dataclasses. Value objects replace loose strings for lifecycle, visibility, gear type and block position. Repository ports use domain types rather than SQLAlchemy models.
This supports the onion boundary:
- The domain states what a capability accepts and returns.
- Adapters implement the protocol.
- Applications compose the adapter.
- Static checking detects a mismatched implementation before runtime.
Pydantic is not imported into gts.domain or gts.ports. It is used where runtime validation is required, including HTTP and message boundaries.
FastAPI endpoints use Pydantic request and response models. The application does not expose ORM models as wire schemas.
The React app generates TypeScript declarations from /openapi.json:
FastAPI routes -> OpenAPI document -> openapi-typescript -> schema.d.ts
The generated schema is committed. just check-app-api regenerates it against the running web application and fails when the checked-in file is stale.
This contract detects:
- Renamed or removed fields.
- Changed nullability.
- Changed enum values.
- Route and response-shape drift.
pgmq commands and events are Pydantic envelopes. Each message type validates its fields before publication and after consumption.
Messages carry identifiers and required values. A consumer reloads the current aggregate rather than accepting an untyped dictionary or serialised ORM object as authority.
The Astro and app projects have separate TypeScript configurations and build checks.
- Astro checks page, component and island source.
- The app runs
tsc --noEmit. - The video package runs TypeScript checking for the parked Remotion code.
- API client types come from OpenAPI rather than handwritten duplication.
Typing and import contracts solve different problems.
- Mypy and TypeScript verify type compatibility.
- Pydantic verifies selected values at runtime boundaries.
-
import-linterverifies dependency direction. - Tests verify behaviour and persistence.
A type-correct import can still violate onion architecture. A legal dependency can still contain incorrect behaviour. The quality gate uses all four checks.
The project does not rely on:
- Serena as an architecture component.
- Runtime
typeguardinstrumentation. - MonkeyType or automatic annotation generation.
- A mypy versus Pyright experiment as a delivery phase.
- Static types as a substitute for domain tests or database constraints.
These tools may be evaluated in future work, but they do not describe the current repository.
New public interfaces require complete types. Existing package coverage should expand by adding a package to the normal gate only when it passes consistently; the project does not weaken strict settings to make a new package appear covered.
The desired order is:
- Core domain and ports.
- Application service boundaries.
- HTTP and message schemas.
- Adapter implementations.
- Supporting scripts where their failure can affect production data.