docs(gateway): gateway-ready conventions & service communication [AYG-74] by amostt · Pull Request #2219 · fastapi/full-stack-fastapi-template

amostt · 2026-02-28T19:46:08Z

Summary

Add Gateway-Ready Conventions section to README covering service discoverability endpoints, routing conventions (/api/v1 prefix), cross-cutting concerns table (template vs gateway responsibility), and managed platform guidance
Add Service-to-Service Communication section to README covering {SERVICE_NAME}_URL env var pattern, shared HttpClient usage with correlation ID propagation, and ServiceError pattern for unconfigured services
Create reference compose.gateway.yml with Traefik 3.6, TLS/ACME (Let's Encrypt), HTTP→HTTPS redirect, rate limiting middleware (commented), and example service labels — clearly marked as "reference only"

Changes

README.md — +113 lines (2 new sections between Deployment and Environment Variables)
compose.gateway.yml — new file, 139 lines (reference-only Traefik gateway config)

Acceptance Criteria

AC-1 README: gateway-ready conventions (discoverability, routing, cross-cutting concerns)
AC-2 Reference compose.gateway.yml with Traefik 3.6 (TLS, rate limiting, Docker provider)
AC-3 Service-to-service communication ({SERVICE_NAME}_URL, HTTP client, correlation ID)
AC-4 Managed platform note (Railway, Cloud Run, Fly.io, Alibaba Cloud)
AC-5 Correlation ID fallback: request_id used when X-Correlation-ID absent/invalid
AC-6 ServiceError(503, "...", "SERVICE_NOT_CONFIGURED") code example

Review Summary

Critical: 0 | High: 0 (4 fixed) | Medium: 5 | Low: 4
No code changes — documentation only
docker compose -f compose.gateway.yml config validates cleanly

Fixed in review cycle

[FUNC-001] Corrected HttpClientDep import path (app.api.deps, not app.core.http_client)
[FUNC-002] Added missing commit and build_time to /version endpoint description
[FUNC-003] Fixed inaccurate claim about HTTP client logging (logs retries/errors, not all requests)
[QUAL-001] Added missing HttpClientDep import to error handling code example
[SEC-004] Specified correlation ID validation format (alphanumeric, hyphens, dots; max 128 chars)
[FUNC-004/SEC-008] Added TLS challenge port 443 caveat with HTTP-01 alternative
[STYLE-002] Added --- separator before Service-to-Service Communication section

Remaining (low/medium — deferred to future stories)

[SEC-001] Docker socket proxy recommendation for hardened deployments
[SEC-002] /version info disclosure advisory note
[SEC-003] Rate limiting activation step in usage instructions
[SEC-005] SSRF guidance for HttpClient URL interpolation

Test Plan

ACME_EMAIL=test@example.com docker compose -f compose.gateway.yml config — validates syntax
Manual review: README sections match PRD Sections 4.1.20 and 4.1.21
Manual review: code examples match actual codebase patterns

Fixes AYG-74
Related to AYG-64

🤖 Generated with Claude Code by Aygentic

Rename default branch from master to main across all CI workflows, documentation, and PRD. Also adds comprehensive project documentation generated by the initialise skill (CLAUDE.md, docs/ structure). 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com>

#1) * feat(core): rewrite config, error handlers, and shared models [AYG-65] - Replace PostgreSQL/SMTP settings with Supabase+Clerk env vars - Add frozen Settings with production secret and CORS guards - Create unified error response shape with global exception handlers - Add shared Pydantic models: ErrorResponse, ValidationErrorResponse, PaginatedResponse, Principal Fixes AYG-65 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(core): untrack .env and guard conftest for migration [AYG-65] - Remove .env from git tracking and add to .gitignore (SEC-001) - Guard integration test conftest.py imports with try/except so unit tests run without --noconftest during the migration (FUNC-002) Related to AYG-65 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(tests): harden test isolation for template usage [AYG-65] - Catch all exceptions (including ValidationError) in conftest guard so pytest doesn't crash when env vars are unset in a fresh template clone - Explicitly delenv missing vars in test_missing_required_var_raises so the test is deterministic regardless of the caller's shell environment Related to AYG-65 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(project): update documentation before merge [skip ci] Updated documentation based on AYG-65 code changes: - setup.md: replaced PostgreSQL/SMTP/JWT env vars with Supabase/Clerk - deployment/environments.md: updated all env tables and GitHub Secrets - architecture/overview.md: added error handling framework, shared models, Clerk auth - architecture/decisions/: new ADRs for error handling and models package - api/overview.md: Clerk auth, standard error shape, paginated response pattern - api/endpoints/login.md: deprecated (Clerk migration) - api/endpoints/users.md + items.md: updated auth and error response docs - data/models.md: new Shared Pydantic Models section - testing/test-registry.md: +36 unit tests, closed config coverage gap Related to AYG-65 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…YG-66] (#2) * feat(core): add structured logging and request pipeline middleware [AYG-66] Add structlog-based structured logging (JSON/console modes) and request pipeline middleware providing UUID v4 request IDs, correlation ID propagation, security headers on all responses (including CORS preflight), and status-based log levels (info/warning/error for 2xx/4xx/5xx). - Create backend/app/core/logging.py: structlog configuration with JSON renderer (production) and ConsoleRenderer (local dev), base fields (timestamp, level, event, service, version, environment), contextvars integration for request-scoped fields - Create backend/app/core/middleware.py: RequestPipelineMiddleware with request_id generation, X-Correlation-ID propagation, 6 security headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy, HSTS production-only), X-Request-ID on every response including error and exception paths - Wire into main.py with documented middleware ordering (outermost wraps CORSMiddleware so preflight OPTIONS get headers too) - 32 new unit tests (6 logging + 26 middleware) covering CORS preflight header behavior, X-Request-ID on 4xx/5xx/exception paths, and negative tests proving Authorization/Cookie values never logged Fixes AYG-66 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(core): update architecture, test registry, and deployment docs for AYG-66 [skip ci] Updated documentation based on structured logging and request pipeline middleware implementation. Related to AYG-66 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…ed deps [AYG-67] (#3) Implement the three core infrastructure dependencies for the microservice template: - Supabase client: factory function + FastAPI dependency from app.state - Clerk JWT auth: validate Bearer tokens, extract Principal with roles, map error reasons to structured error codes (AUTH_MISSING_TOKEN, AUTH_EXPIRED_TOKEN, AUTH_INVALID_TOKEN) - HTTP client wrapper: async httpx with retry on 502/503/504, exponential backoff, circuit breaker (5 failures/60s window), X-Request-ID/X-Correlation-ID header propagation from structlog - Typed FastAPI dependencies: SupabaseDep, PrincipalDep, HttpClientDep, RequestIdDep via Annotated[T, Depends()] - Lifespan context manager: init Supabase + HttpClient at startup, close httpx pool on shutdown - Added session_id field to Principal model 44 new unit tests (113 total), all passing. Fixes AYG-67 🤖 Generated by Aygentic Co-authored-by: Aygentic <noreply@aygentic.com>

#4) * feat(api): add operational endpoints health/readiness/version [AYG-68] - Add /healthz, /readyz, /version root endpoints - Add readiness Supabase check with resilient 503 response path - Add integration tests for schemas, auth-free access, and failure paths Fixes AYG-68 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(api): address code review findings for health endpoints [AYG-68] - Offload sync Supabase check to thread pool via anyio.to_thread.run_sync to avoid blocking the async event loop (BUG-001) - Use select("*", head=True) for lighter HEAD connectivity probe (QUAL-001) - Add explicit AttributeError catch for missing Supabase client (QUAL-002) - Replace str(exc) with error_type= in logger to prevent credential leak (SEC-001) - Patch settings in test_includes_service_name and test_default_values_for_unset_env_vars for CI robustness (TEST-001, TEST-002) - Strengthen test_exception_does_not_crash to assert full body values (TEST-003) Related to AYG-68 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…y [skip ci] (#5) - Create docs/api/endpoints/health.md with full schema docs for /healthz, /readyz, and /version including Kubernetes probe YAML examples - Update docs/api/overview.md to add "Operational Endpoints" section at root level and mark legacy /utils/health-check/ as superseded - Update docs/testing/test-registry.md: add 17 health integration tests, coverage 188 → 205 total Related to AYG-68 🤖 Generated by Aygentic Co-authored-by: Aygentic <noreply@aygentic.com>

…n [AYG-69] (#6) * feat(entity): add Entity models, service layer, and database migration [AYG-69] Implements the entity resource foundation for the microservice starter template: - Pure Pydantic models: EntityBase, EntityCreate, EntityUpdate, EntityPublic, EntitiesPublic with field validation (title 1-255 chars, description <= 1000) - Service layer with CRUD operations via supabase-py table builder pattern: create_entity, get_entity, list_entities, update_entity, delete_entity - All operations enforce ownership via owner_id filtering - Pagination with offset/limit (capped at 100, clamped to valid range) - Structured error handling: APIError → 404, infrastructure errors → 500 - Generic error messages (no exception details leaked to clients) - Supabase SQL migration: entities table, owner index, updated_at trigger, RLS policies with WITH CHECK on UPDATE - 34 unit tests covering happy paths, edge cases, and error handling Fixes AYG-69 Related to AYG-64 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(project): update documentation for entity models and service layer [skip ci] Updated 6 docs, created 2 new docs based on AYG-69 code changes: - Data models: entities table, schema family, migration history - Architecture: service layer component, Entity CRUD flow diagram, ADR-0004 - API: pre-scaffolded entity endpoints (planned for AYG-70) - Deployment: Supabase CLI migrations section - Testing: 34 new test entries in test-registry Related to AYG-69 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…YG-70] (#7) Add 5 thin route handlers (POST/GET/GET/{id}/PATCH/{id}/DELETE/{id}) for the Entity resource at /api/v1/entities. All endpoints require Clerk JWT authentication via PrincipalDep and delegate business logic to entity_service. Pagination validated at route layer via Query constraints (offset>=0, limit 1-100). Includes 22 integration tests covering CRUD lifecycle, auth enforcement, ownership isolation (404 not 403), validation errors, and pagination boundary rejection. Files: - CREATE backend/app/api/routes/entities.py (5 route handlers) - MODIFY backend/app/api/main.py (register entities router) - CREATE backend/tests/integration/test_entities.py (22 tests) Fixes AYG-70 Related to AYG-64 🤖 Generated by Aygentic Co-authored-by: Aygentic <noreply@aygentic.com>

* feat(api): add Entity CRUD REST endpoints with auth and pagination [AYG-70] Add 5 thin route handlers (POST/GET/GET/{id}/PATCH/{id}/DELETE/{id}) for the Entity resource at /api/v1/entities. All endpoints require Clerk JWT authentication via PrincipalDep and delegate business logic to entity_service. Pagination validated at route layer via Query constraints (offset>=0, limit 1-100). Includes 22 integration tests covering CRUD lifecycle, auth enforcement, ownership isolation (404 not 403), validation errors, and pagination boundary rejection. Files: - CREATE backend/app/api/routes/entities.py (5 route handlers) - MODIFY backend/app/api/main.py (register entities router) - CREATE backend/tests/integration/test_entities.py (22 tests) Fixes AYG-70 Related to AYG-64 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(api): activate entity endpoint docs and test registry updates [AYG-70] --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…AYG-71] (#9) * feat(api): wire app assembly with lifespan, Sentry, and error tests [AYG-71] Move Sentry SDK init into FastAPI lifespan startup (conditional on SENTRY_DSN) so it activates after settings validation. Add structured startup/shutdown log events with service_name, version, environment. Flush Sentry on shutdown for graceful SIGTERM handling. Remove broken legacy route imports from api/main.py (items, login, private, users, utils) that reference deleted deps — entities is the only active router. Rewrite conftest.py with modern test fixtures using Supabase and Clerk dependency overrides against the real assembled app. Legacy fixtures remain guarded for AYG-72 cleanup. Add 7 integration tests verifying unified error response shape (401/404/422/500), request_id propagation, security headers, and X-Request-ID header across the full middleware + handler pipeline. Fixes AYG-71 Related to AYG-64 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(api): reorder lifespan shutdown to log → close → flush (AC-10) Reorder the shutdown sequence in the lifespan context manager so that the app_shutdown log event is emitted first, followed by closing the HTTP client, then flushing Sentry — matching the AC-10 specification. Add 3 focused tests in test_lifespan.py asserting exact call order, http_client close invocation, and sentry flush with timeout=2.0. Related to AYG-71 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(api): update documentation before merge [skip ci] Update all affected documentation for AYG-71 FastAPI App Assembly: - test-registry.md: add 49 new unit tests (lifespan, http_client, supabase, auth) and 7 integration tests (error_responses); update coverage totals to 321 - architecture/overview.md: add lifespan sequence diagram, new core components, update C4 context with Supabase; advance ADR 0001/0002/0004 to accepted - api/overview.md: remove legacy routes, document unified error shape - api/endpoints: mark items/login/users as deprecated (removed from router) - data/models.md: add missing Principal.session_id field - getting-started/setup.md: update env vars (Supabase/Clerk replaces Postgres/SMTP) - deployment/environments.md: add production security constraint notes - deployment/ci-pipeline.md: update test dirs, document new deps and env vars - runbooks/incidents.md: add Sentry lifespan init and shutdown flush notes Related to AYG-71 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

… [AYG-72] (#10) * feat(infra): Docker, CI & legacy cleanup for Supabase/Clerk migration [AYG-72] Remove all legacy SQLModel/PostgreSQL/JWT/email code, tests, Alembic migrations, and dependencies. Rewrite Dockerfile as multi-stage build with OCI labels, non-root user, and Python healthcheck. Replace test-backend.yml + test-docker-compose.yml with unified ci.yml (lint → test → docker-build → alls-green). Add WITH_UI compose profile gating frontend service. Create .env.example documenting all modern environment variables. Update deploy workflows and prestart script for Supabase-managed infrastructure. - Delete 44 legacy files (models, routes, CRUD, JWT auth, email templates, Alembic migrations, legacy tests) - Remove 7 legacy dependencies (sqlmodel, alembic, psycopg, pyjwt, pwdlib, emails, jinja2) - Rewrite backend/Dockerfile with builder+runtime stages, uv, non-root user - Rewrite compose.yml removing db/adminer/prestart/mailcatcher services - Add profiles: ["ui"] on frontend service for WITH_UI flag - Create .github/workflows/ci.yml with frontend gating via hashFiles - Update deploy-staging.yml and deploy-production.yml for modern env vars - Create .env.example with sectioned variable documentation 198 tests passing | Lint clean | 0 new mypy errors Fixes AYG-72 Related to AYG-64 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(ci): correct CI workflow paths, build context, and branch gate Fix 5 issues found during automated code review: - BUG-001: Docker build context now uses repo root (.) matching compose.yml - BUG-002: Replace invalid `bun ci` with `bun install --frozen-lockfile` - FUNC-001: Fix lint/mypy paths to use `app/` relative to working-directory - FUNC-002: Add frontend-ci to alls-green gate with allowed-skips - SEC-001: Create root .dockerignore to exclude secrets from build context Related to AYG-72 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(ci): stabilize pre-commit and Playwright workflows for template mode - Replace invalid `bun ci` with `bun install --frozen-lockfile` in pre-commit.yml and playwright.yml (3 occurrences) - Add TEMPLATE_REPO_MODE repository variable guard on test-playwright job so Playwright matrix is skipped in template/bootstrap repos - Guard merge-playwright-reports to skip when test-playwright is skipped - Provide dummy env vars (SUPABASE_URL, SUPABASE_SERVICE_KEY, CLERK_SECRET_KEY) for generate-client.sh so app config import does not crash during CI bootstrap alls-green-playwright already has allowed-skips: test-playwright, so the branch protection gate remains green when skipped. Related to AYG-72 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * chore(ci): add descriptive comment to ci.yml to trigger PR check suite GitHub Actions does not create check suites for new workflow files on their first pull_request event. Re-push to force synchronize. Related to AYG-72 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(ci): resolve pre-commit mypy failures and flip Playwright to opt-in - Fix http_client.py type annotations: **kwargs: object → Any (standard pattern for kwargs forwarding), remove stale type: ignore[misc], fix type: ignore[return-value] → [no-any-return]. Zero behavior change. Resolves 13 pre-existing mypy errors that blocked every PR. - Flip Playwright guard from opt-out (TEMPLATE_REPO_MODE != 'true') to opt-in (PLAYWRIGHT_ENABLED == 'true'). Default state = skip = green alls-green gate. Eliminates bootstrapping problem where undefined variable caused tests to run and fail on template repos. Related to AYG-72 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * fix(ci): remove upstream workflow and resolve remaining mypy errors - Remove add-to-project.yml: targets fastapi/projects/2 (upstream org), uses nonexistent PROJECTS_TOKEN secret, and calls deprecated GitHub Projects Classic API. Irrelevant to AYG-64 Microservice Template. - Fix config.py:12 no-any-return: assign json.loads() result to typed variable before returning. Zero behavior change. - Fix auth.py:16 attr-defined: import AuthenticateRequestOptions from clerk_backend_api.jwks_helpers (where it is defined and exported) instead of top-level clerk_backend_api (runtime-accessible via dynamic lookup but not visible to mypy). Zero behavior change. Result: mypy 0 errors across 22 files, 198 tests passing. Related to AYG-72 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…YG-73] (#11) * feat(deploy): add GHCR deployment workflows with image-based promotion [AYG-73] Replace legacy self-hosted Docker Compose deploy workflows with GHCR-based CI/CD pipeline. Staging builds and pushes to GHCR on every push to main. Production promotes the exact staging image by re-tagging (no rebuild), guaranteeing identical binaries across environments. Key changes: - deploy-staging.yml: ubuntu-latest, docker/build-push-action, SHA+staging tags, concurrency with cancel-in-progress, 5 pluggable deploy blocks - deploy-production.yml: image promotion (pull→re-tag→push), semver+latest tags, concurrency without cancel-in-progress, 5 pluggable deploy blocks - .env.example: added Deployment (CI/CD) section with platform secret placeholders - README.md: rewritten with full deployment docs (environment model, GHCR tagging, staging/production flows, rollback, pre-production checklist, Supabase migrations) - docs/deployment/ci-pipeline.md: updated staging/production sections, secrets tables, self-hosted runners now optional - docs/deployment/environments.md: updated deploy processes, rollback procedures, health check URLs, platform-specific secrets Pluggable deploy targets: Railway, Alibaba Cloud (ACR+ECS), Google Cloud Run, Fly.io, Self-hosted (Docker Compose via SSH). Fixes AYG-73 Related to AYG-64 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> * docs(deploy): fix residual doc gaps from GHCR workflow migration [skip ci] Add missing Alibaba Cloud secrets to ci-pipeline.md and environments.md platform tables. Fix stale test-backend.yml reference in ci-pipeline.md frontmatter (replaced by ci.yml in AYG-72). Add GHCR-native image rollback procedure to incidents.md alongside git-revert path. Related to AYG-73 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com> --------- Co-authored-by: Aygentic <noreply@aygentic.com>

…ocs, and reference compose [AYG-74] Add Gateway-Ready Conventions and Service-to-Service Communication sections to README covering service discoverability endpoints, routing conventions, cross-cutting concerns table, managed platform guidance, {SERVICE_NAME}_URL env var pattern, shared HTTP client usage with correlation ID propagation, and ServiceError pattern for unconfigured services. Create reference compose.gateway.yml with Traefik 3.6, TLS/ACME, HTTP-to-HTTPS redirect, rate limiting middleware (commented), and example service labels — clearly marked as reference-only for self-hosted deployments. Fixes AYG-74 Related to AYG-64 🤖 Generated by Aygentic Co-Authored-By: Aygentic <noreply@aygentic.com>

amostt · 2026-02-28T19:46:24Z

Accidentally opened against upstream — closing. Correct PR will be on Aygentic/Aygentic-starter-template.

amostt and others added 14 commits February 27, 2026 03:54

docs: add PRD for microservice-template-foundation

96fa33e

amostt closed this Feb 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(gateway): gateway-ready conventions & service communication [AYG-74]#2219

docs(gateway): gateway-ready conventions & service communication [AYG-74]#2219
amostt wants to merge 14 commits intofastapi:masterfrom
Aygentic:feature/AYG-74-next-story

amostt commented Feb 28, 2026

Uh oh!

amostt commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

amostt commented Feb 28, 2026

Summary

Changes

Acceptance Criteria

Review Summary

Fixed in review cycle

Remaining (low/medium — deferred to future stories)

Test Plan

Uh oh!

amostt commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant