{"id":48832659,"url":"https://github.com/mesteriis/fullstack-template","last_synced_at":"2026-04-14T21:03:30.606Z","repository":{"id":346846031,"uuid":"1191854302","full_name":"Mesteriis/fullstack-template","owner":"Mesteriis","description":"Opinionated FastAPI + Vue fullstack template with contract parity checks, ADR-driven governance, and observability baseline.","archived":false,"fork":false,"pushed_at":"2026-03-26T17:37:33.000Z","size":733,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T18:41:38.035Z","etag":null,"topics":["adr","architecture","fastapi","fullstack","observability","openapi","python","template","typescript","vue"],"latest_commit_sha":null,"homepage":"https://mesteriis.github.io/fullstack-template/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mesteriis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T16:44:47.000Z","updated_at":"2026-03-26T17:37:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Mesteriis/fullstack-template","commit_stats":null,"previous_names":["mesteriis/registries"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Mesteriis/fullstack-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesteriis%2Ffullstack-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesteriis%2Ffullstack-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesteriis%2Ffullstack-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesteriis%2Ffullstack-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mesteriis","download_url":"https://codeload.github.com/Mesteriis/fullstack-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mesteriis%2Ffullstack-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31815083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architecture","fastapi","fullstack","observability","openapi","python","template","typescript","vue"],"created_at":"2026-04-14T21:03:25.190Z","updated_at":"2026-04-14T21:03:30.582Z","avatar_url":"https://github.com/Mesteriis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fullstack Template\n\n`Fullstack Template` is a reusable engineering template for teams that want a\nstrict fullstack baseline instead of an empty starter.\n\nIt is designed to make the first 5 to 10 minutes in the repository predictable:\n\n- what the template is;\n- what is already implemented;\n- how to run it locally;\n- which rules are mandatory;\n- which files are the source of truth;\n- which parts are only baseline/reference slices, not finished product features.\n\n## What Is Included\n\n- `src/backend/`: FastAPI backend with bounded-context layout, typed settings,\n  explicit Unit of Work, structured error model, observability bootstrap,\n  pytest/Testcontainers baseline, and import-boundary enforcement.\n- `src/frontend/`: Vue 3 frontend with layered `app/pages/features/entities/shared`\n  structure, router + shell, local UI adapter boundary, typed config, shared API\n  client, OpenAPI-derived generated API bindings, frontend observability baseline,\n  and unit/component tests.\n- `specs/`: contract-first source artifacts. OpenAPI lives here and remains the\n  canonical HTTP API contract.\n- `docs/adr/`: architecture decisions, engineering governance, and sample\n  domain/product ADRs used as reference material for derived projects.\n- `scripts/`, `Makefile`, `.pre-commit-config.yaml`: local and CI quality gates\n  that enforce the template instead of leaving rules as documentation only.\n- `docker/`, `migrations/`, `.github/`, `.gitea/`: baseline delivery and CI/CD\n  assets for reuse.\n\n## Current Status\n\nThis repository is a template baseline, not a finished product.\n\nWhat is production-oriented already:\n\n- repository governance and self-checks;\n- backend and frontend architecture boundaries;\n- observability baseline on both sides;\n- testing, linting, type checking, security and Docker build paths;\n- one end-to-end reference slice built around system health.\n\nWhat is intentionally still baseline/reference:\n\n- the business/domain surface is intentionally thin;\n- frontend homepage explains the template instead of acting like a real dashboard;\n- local `shared/ui` primitives are adapters, not a branded design system;\n- product ADRs describe reference domain decisions, not a claim that the full\n  product is already implemented here.\n\n## Quick Start\n\nPublic docs site:\n\n- `https://mesteriis.github.io/fullstack-template/`\n\n1. Copy the shared env file:\n\n   ```bash\n   make init-env\n   ```\n\n   Backend env namespaces are section-scoped: `APP__`, `API__`, `DB__`,\n   `BROKER__`, `SYSTEM__`, `OBSERVABILITY__`. Frontend reads the same root `.env`, derives\n   its shared app/observability defaults from those namespaces, and only exposes\n   a safe frontend subset plus optional `VITE_*` overrides to browser code.\n\n2. Install dependencies and hooks:\n\n   ```bash\n   make bootstrap\n   ```\n\n   `pre-commit` stays path-scoped for fast local feedback. `pre-push` now runs\n   the full `make ci` pipeline before anything is sent to CI.\n\n3. Choose one local runtime mode.\n\n   Full Docker ensemble:\n\n   ```bash\n   make compose-up\n   ```\n\n   Manual mode:\n   start PostgreSQL and Redis yourself, for example:\n\n   ```bash\n   docker run -d --name fullstack-template-postgres \\\n     -e POSTGRES_USER=fullstack_template \\\n     -e POSTGRES_PASSWORD=fullstack_template \\\n     -e POSTGRES_DB=fullstack_template \\\n     -p 5432:5432 postgres:17\n\n   docker run -d --name fullstack-template-redis \\\n     -p 6379:6379 redis:7-alpine\n   ```\n\n4. Manual mode only: apply migrations:\n\n   ```bash\n   cd src/backend \u0026\u0026 make migrate\n   ```\n\n5. Manual mode only: run the backend:\n\n   ```bash\n   cd src/backend \u0026\u0026 uv run uvicorn main:app --reload\n   ```\n\n6. Manual mode only: run the frontend in another terminal:\n\n   ```bash\n   cd src/frontend \u0026\u0026 make dev\n   ```\n\n## Local URLs\n\n- Frontend shell: `http://localhost:5173/`\n- Backend root metadata: `http://localhost:8000/`\n- Backend API docs: `http://localhost:8000/docs`\n- Health endpoint: `http://localhost:8000/api/v1/system/health`\n- Readiness endpoint: `http://localhost:8000/api/v1/system/readyz`\n- Liveness endpoint: `http://localhost:8000/api/v1/system/livez`\n\n## Daily Commands\n\n- `make doctor`: validate required tooling and repository invariants\n- `make init-env`: create or refresh the shared `.env`\n- `make check`: run repository invariants\n- `make lint`: run backend, frontend and repo linting\n- `make test`: run backend and frontend tests\n- `make frontend-api-generate`: regenerate frontend API bindings from OpenAPI\n- `make contract-test`: run cross-app contract checks from `tests/contract/`\n- `make e2e-test`: run root-level smoke scenarios from `tests/e2e/`\n- `make build`: run type checks and frontend build\n- `make docs-build`: build the GitHub Pages documentation portal\n- `make docs-dev`: run the GitHub Pages documentation portal locally\n- `make compose-up`: start the root Docker ensemble\n- `make compose-down`: stop the root Docker ensemble\n- `make ci`: run the full golden-master local pipeline\n\nApp-local command surfaces also exist:\n\n- `cd src/backend \u0026\u0026 make help`\n- `cd src/frontend \u0026\u0026 make help`\n\n## Docker Compose\n\n- Full local ensemble: `make compose-up`\n- Backend-only stack: `docker compose --env-file .env -f src/backend/docker-compose.yml up --build`\n- Frontend-only shell: `docker compose --env-file .env -f src/frontend/docker-compose.yml up --build`\n\nNotes:\n\n- root compose starts `postgres`, `redis`, `backend`, and `frontend`;\n- backend compose starts `postgres`, `redis`, and `backend`;\n- frontend compose starts only the nginx-served frontend shell and proxies `/api`\n  to `BACKEND_UPSTREAM`, which defaults to `http://host.docker.internal:8000`.\n- backend migration tests use `pytest-alembic` plus `testcontainers`; they create\n  a dedicated PostgreSQL database inside the test container and never run\n  against a live local database.\n- if local ports are busy, override `POSTGRES_HOST_PORT`, `REDIS_HOST_PORT`,\n  `BACKEND_HOST_PORT`, or `FRONTEND_HOST_PORT` for the compose command.\n\n## Repository Structure\n\n```text\n.\n├── src/\n│   ├── backend/        # FastAPI service, runtime, tests, migrations ownership\n│   └── frontend/       # Vue 3 app, layered UI boundary, frontend tests\n├── docs/\n│   ├── getting-started.md\n│   ├── template/\n│   ├── frontend/\n│   └── adr/\n├── specs/              # canonical OpenAPI / AsyncAPI / JSON Schema contracts\n├── scripts/            # repository checks and local automation entrypoints\n├── docker/             # reusable container/runtime assets\n├── migrations/         # Alembic migrations\n├── Makefile\n└── .pre-commit-config.yaml\n```\n\n## Source Of Truth\n\n- HTTP API contract: [specs/openapi/platform.openapi.yaml](./specs/openapi/platform.openapi.yaml)\n- Contract-first rules: [specs/README.md](./specs/README.md)\n- Parity enforcement: [scripts/check_http_contract_parity.py](./scripts/check_http_contract_parity.py)\n  This check derives the expected HTTP surface from OpenAPI and compares it with backend runtime OpenAPI and frontend bindings.\n- Frontend generated API: [src/frontend/shared/api/generated/platform-api.ts](./src/frontend/shared/api/generated/platform-api.ts)\n- Template philosophy: [docs/template/PHILOSOPHY.md](./docs/template/PHILOSOPHY.md)\n- Architecture reading map: [docs/adr/INDEX.md](./docs/adr/INDEX.md)\n- Contribution workflow: [CONTRIBUTING.md](./CONTRIBUTING.md)\n- Local/CI control plane: [Makefile](./Makefile), [scripts/](./scripts/), [.pre-commit-config.yaml](./.pre-commit-config.yaml)\n\nIf implementation and documentation disagree, fix the disagreement. The repo is\nnot supposed to rely on tribal knowledge.\n\n## Reference Slice Already Implemented\n\nThe current canonical reference slice is `system health`.\n\nIt includes:\n\n- backend endpoints under `/api/v1/system/health`, `/readyz`, `/livez`;\n- typed backend contracts for readiness and dependency checks;\n- concurrent dependency probing bounded by settings-driven timeout rules;\n- safe externally-exposed failure details with structured backend logs for operators;\n- a frontend feature that reads the health contract through the shared API client;\n- homepage composition that demonstrates the layered frontend shell;\n- tests on backend API behavior and frontend rendering.\n\nTreat this slice as a sample of how to build the next bounded context or feature,\nnot as the beginning of a product dashboard.\n\n## What To Read First\n\n1. This `README.md`\n2. [docs/getting-started.md](./docs/getting-started.md) or the public docs portal at `https://mesteriis.github.io/fullstack-template/`\n3. [CONTRIBUTING.md](./CONTRIBUTING.md)\n4. [docs/adr/INDEX.md](./docs/adr/INDEX.md)\n\n## What To Customize For A Real Project\n\n- application name, env values and deployment metadata;\n- domain-specific OpenAPI/AsyncAPI/JSON Schema contracts in `specs/`;\n- bounded contexts under `src/backend/apps/`;\n- frontend pages/features/entities built on top of the shared UI/API boundaries;\n- external observability endpoints and GlitchTip/OTLP settings;\n- product/domain ADRs to match the real problem space;\n- CI secrets, container registry settings and deployment topology.\n\n## Notes For Derived Projects\n\n- Keep the strictness if you keep the scope.\n- Remove unused template parts deliberately instead of weakening checks in place.\n- Do not treat the reference slice or sample ADRs as mandatory product shape.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesteriis%2Ffullstack-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmesteriis%2Ffullstack-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmesteriis%2Ffullstack-template/lists"}