Architecture contract container for stack, dependency policy, repo/process, secrets, toolchain, validation, and deploy posture rules.

Sections

• Stack: runtime topology, host, language/runtime boundaries
• Dependencies: dependency policy, machine allowlist
• Repo and process: repo rules, process rules, tooling

Rules

1. [locked] Secrets go through SOPS only. No plaintext .env files anywhere, under any name. A .gitignore is NOT protection. Docs reference SOPS pointers + commands, never raw values.
2. [locked] uv is the only Python package manager/toolchain for Python services (services/api). Python dependencies are declared in pyproject.toml and allowlisted in governance/allowed-deps.json (gated by governance/scripts/check-python-deps.py, which scans pyproject.toml; npm package.json is gated by governance/scripts/check-deps.mjs). ruff is the only Python linter/formatter; pydantic-settings is the only config/env loader. uv itself is the toolchain, not an allowlisted dependency.
3. [locked] Governance contract JSON and API payload schemas are validated against JSON Schema (the standard) using ajv (the npm validator). Schemas live in governance/schemas/; governance/scripts/check-contracts.mjs validates every governance/contracts/*.json against its schema.

Enforced by

scripted scan + JSON Schema validation + dependency-cruiser + dependency allowlist gates — derived from these rules

• Secrets scan — flags any plaintext secret / .env file committed to the repo.
• Contract validation — validates governance contract JSON with governance/scripts/check-contracts.mjs.
• Imports rule (dependency-cruiser, pending) — enforces path-alias and import-order conventions.
• Dependency allowlist enforcement stays in governance/allowed-deps.json, checked by governance/scripts/check-deps.mjs and governance/scripts/check-python-deps.py.

Open items

• Imports & path aliases: alias map + import order (e.g. simple-import-sort) — define and lock.
• File & directory naming: PascalCase components, camelCase hooks/utils, colocated tests — confirm and lock.
• Commit conventions: commitlint config — confirm and lock.
• Stack, dependency, repo, and process rules must be ratified one at a time before encoding.

Dependency allowlist

The live allowlist remains governance/allowed-deps.json because dependency gates read its structure.

Allowed today

tooling

• ajv
• dependency-cruiser
• madge

apps/web

• @neondatabase/serverless
• better-auth
• drizzle-orm
• wrangler

services/api

• fastapi
• uvicorn
• sqlalchemy
• alembic
• sqladmin
• pydantic-settings
• psycopg2-binary
• ruff

apps/devdocs

• @tailwindcss/postcss
• @types/mdx
• cross-env
• fumadocs-core
• fumadocs-mdx
• fumadocs-ui
• mermaid
• next
• next-themes
• react
• react-dom
• remark-directive
• shiki
• @types/node
• @types/react
• @types/react-dom
• typescript
• wrangler