Coding conventions

Python (tappass/, tappass-sdk/, assess/, license-server/)

• Formatter: ruff format (configured in each repo’s pyproject.toml)
• Linter: ruff check --fix
• Type check: mypy --strict — treat type errors as build failures
• Tests: pytest. Coverage target >85% on new code; integration tests prefer real Postgres over mocks
• Async: Prefer async def for I/O-bound code. Mixing sync and async causes the deadlock — if unsure, read the TrustEngine async notes in the tappass repo.

Layout per service

src/
  api/             # FastAPI routes (thin — no business logic)
  domain/          # Pure Python; no I/O
  adapters/        # I/O: DB, HTTP clients, vault, LLM providers
  pipeline/        # Governance steps, one per file
  config/          # Pydantic Settings
  main.py          # Composition root
tests/
  unit/
  integration/     # Real Postgres, real HTTP (httpx.MockTransport)

Keep domain/ pure — no database, no HTTP, no env vars. Adapters inject everything.

Error handling

• Raise domain exceptions (PolicyBlockError, DetectionError) from domain/ and pipeline/
• Translate to HTTP at the route layer only
• Don’t add try/except blocks “just in case” — let exceptions bubble unless you have a specific recovery

TypeScript (docs/, docs-internal/, frontend/ in tappass/)

• Formatter: Prettier (runs on commit)
• Linter: ESLint (eslint-config-next in frontend, stock in Astro sites)
• Type check: tsc --noEmit in CI
• React: functional components only, no class components
• Styles: Tailwind; avoid bespoke CSS unless absolutely necessary

Git

• Branches: feat/…, fix/…, chore/…, docs/…
• Commits: Conventional Commits, but pragmatic — feat(api): add /health route not feat(api.routes.health): …
• No direct pushes to main. Every change is a PR with at least one review
• Squash & merge only

Security

• Never git add .env — .env* is in .gitignore; confirm before committing
• Secrets go in 1Password (TapPass — Engineering vault), not in repos
• Customer API keys (tp_*) never appear in logs, commits, or screenshots
• See Secret management for rotation procedure