SREDSimplify Engineering

Appearance

Engineering conventions ​

Norms for day-to-day work in this monorepo. When in doubt, match patterns in existing modules and ask in PR review.

Pull requests and review ​

  • At least one approval before merge to main.
  • Keep PRs focused: unrelated cleanups belong in separate PRs unless trivial.
  • Link issues (Fixes #123) when closing tracked work.
  • For user-visible behavior, include screenshots or short clips when helpful.

Commits and releases ​

  • Conventional Commits — feat:, fix:, docs:, chore:, etc.
  • Application production deploys from semantic version tags (vX.Y.Z), not from every merge to main. Release automation is described in Tooling reference and AGENTS.md.

Architecture and design docs ​

  • ADRs (architecture decision records) live under docs/wiki/decisions/. Any change that alters long-lived boundaries (auth, data stores, cross-service contracts) should have or update an ADR.
  • RFCs for cross-cutting proposals live under Projects → RFCs; see that page for when to use an RFC vs a PR description.

Code style by stack ​

Frontend (frontend/) ​

  • TypeScript strictness: follow existing tsconfig and ESLint rules; run npm run lint and npm run typecheck.
  • React / Next.js — Prefer server/client boundaries already used in the App Router layout; avoid widening scope in shared layout files without review.
  • State — Zustand for client state, TanStack Query for server state (do not introduce Redux without an ADR).

Backend (backend/) ​

  • Java 21, Spring Boot layered structure (controllers → services → repositories).
  • Prefer constructor injection, meaningful domain exceptions, and tests for regressions in auth and billing paths.
  • Native SQL using PostgreSQL features (ILIKE, etc.) is intentional; do not “port” to H2 assumptions.

Python service (backend/python-service/) ​

  • Follow FastAPI patterns already in the service; use uv per project docs.
  • Treat the service as stateless workers unless a doc explicitly introduces shared state.

Security and production safety ​

  • Never commit secrets — use Doppler or CI secrets; redact tokens in logs and screenshots.
  • JWT header — Backend expects the custom auth header for the app API (see architecture docs); do not “fix” to Authorization without coordinated backend + client change.
  • Destructive operations — database migrations, cache flushes, and infra changes require explicit review and usually a runbook link.

Docs and workflows ​

  • GitHub Agentic Workflows: edit Markdown sources under .github/workflows/*.md, then run gh aw validate && gh aw compile — never hand-edit .lock.yml files.
  • After changing release or deploy behavior, update Tooling reference and any affected runbooks in the same PR when possible.

Testing and observability ​

  • Add or extend automated tests with the feature; flaky tests must be fixed or quarantined with an owner.
  • Prefer structured logging and correlation IDs where the backend already does so.