https://github.com/matadcze/fullstack-agents
Production-Ready FastAPI + Next.js Template with Auth, Observability, and Agent Scaffold
https://github.com/matadcze/fullstack-agents
agents boilerplate-template devops fastapi grafana llm nextjs redis template typescript
Last synced: 2 months ago
JSON representation
Production-Ready FastAPI + Next.js Template with Auth, Observability, and Agent Scaffold
- Host: GitHub
- URL: https://github.com/matadcze/fullstack-agents
- Owner: matadcze
- Created: 2025-12-09T15:38:13.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T19:22:34.000Z (4 months ago)
- Last Synced: 2026-02-14T02:28:42.067Z (4 months ago)
- Topics: agents, boilerplate-template, devops, fastapi, grafana, llm, nextjs, redis, template, typescript
- Language: Python
- Homepage:
- Size: 595 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# {{PROJECT_NAME}} Full-Stack Template
Reusable FastAPI + React (Next.js) starter with JWT auth, audit logging, async SQLAlchemy, Celery workers, Docker Compose, Prometheus, and Grafana dashboards.
## What's Included
- **Backend (FastAPI)**: Auth & audit routes, async SQLAlchemy + Alembic, Redis-backed rate limiting, Prometheus metrics, structured logging, Celery worker/beat scaffolding.
- **Frontend (Next.js + TypeScript)**: Auth flows (login/register/profile), protected dashboard shell, typed API client, Tailwind styles.
- **Agent scaffold**: Stub LLM provider with `/api/v1/agents/run` endpoint and frontend demo page to submit prompts.
- **Ops**: Docker Compose for Postgres, Redis, backend, frontend, Prometheus, Grafana; health/readiness endpoints; Makefile helpers.
## Using This Template
1) Replace placeholders:
- `{{PROJECT_NAME}}` → human-readable name
- `{{PROJECT_NAME_SLUG}}` / `{{PROJECT_NAME_LOWER}}` → lowercase/slug used in container names and defaults
2) Copy env files and fill in secrets:
```
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
```
- Set `DATABASE_URL`, `JWT_SECRET_KEY` (e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`), and adjust any hostnames/ports.
- When using Docker/nginx, set `NEXT_PUBLIC_API_URL` to `https://localhost` in `frontend/.env` (nginx terminates TLS with the bundled self-signed cert). For local Next.js dev (`npm run dev`) that talks directly to the backend, override to `http://localhost:8000` in `frontend/.env.local`.
- For local Next.js runs, you can also place `NEXT_PUBLIC_*` values in `frontend/.env.local`.
3) Local dev (no Docker):
```
make backend-install
make frontend-install
cd backend && uv run alembic upgrade head
make dev # runs uvicorn + next dev
```
4) Full stack with Docker:
```
docker compose up -d --build
```
Services: nginx entrypoint `:80` (proxies frontend + backend), backend `:8000`, frontend `:3000`, Prometheus `:9091`, Grafana `:3001` (admin/admin).
## Developer Tooling
- Git hooks: `make pre-commit-install` to add hooks (ruff/black/isort/mypy + frontend lint/format). Run on demand with `make pre-commit`.
- Lint/format: `make lint` (backend + frontend) and `make format` to apply fixes. Backend type checks via `make backend-typecheck`.
- Sample data: `make seed` loads fixture users (e.g., admin@example.com / ChangeMe123!) and basic audit events for local testing.
- Frontend formatting uses Prettier; linting runs ESLint flat config in `frontend/eslint.config.mjs`.
## Project Structure
```
.
├── backend/ # FastAPI service, Alembic migrations, Celery worker
├── frontend/ # Next.js app with auth flows
├── prometheus/ # Prometheus scrape config
├── grafana/ # Provisioning + dashboards
├── docker-compose.yml
└── Makefile
```
## Environment Variables
- Canonical examples: `backend/.env.example` and `frontend/.env.example`
- Key values: `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET_KEY`, `NEXT_PUBLIC_API_URL`, `APP_NAME`, `LLM_PROVIDER`, `LLM_MODEL`, `LLM_API_KEY`
- Docker Compose reads `backend/.env` for backend services and `frontend/.env` (with `NEXT_PUBLIC_API_URL=http://localhost`) for the nginx entrypoint.
## Scaling & Sessions
- **Backend workers**: The provided compose files run a single Uvicorn process. For horizontal scale, run multiple backend replicas behind nginx or a load balancer and set `UVICORN_WORKERS` (or switch to gunicorn+uvicorn workers) based on CPU cores. Keep migrations as a one-shot job to avoid race conditions when scaling.
- **Celery**: Scale `celery-worker` replicas independently for background throughput. `celery-beat` should stay singleton.
- **Sessions/state**: The app is stateless (JWT auth), so horizontal scaling is safe. Redis is used for rate limiting; if you add server-side sessions or websockets, plan for a shared store (Redis) and sticky sessions where needed.
- **Redis persistence**: Persistence is disabled by default (see compose files). Enable AOF/RDB only if you need durable state beyond caching/rate-limit counters. For production durability, use a managed Redis or mount a volume with the desired persistence mode.
## Testing
- Backend: `make backend-test` (pytest sample health test) and `make backend-typecheck` (mypy)
- Frontend: `make frontend-test` / `npm run test:e2e` (Playwright sample, adjust selectors as you extend UI)
## Next Steps
- Add your domains: extend `backend/src/domain` and `backend/src/api/v1`
- Expand frontend pages/components for your use case
- Wire CI/CD (lint, test, build images) for your target platform