syndarix/AGENTS.md

AGENTS.md

AI coding assistant context for FastAPI + Next.js Full-Stack Template.

Quick Start

# Backend (Python with uv)
cd backend
make install-dev              # Install dependencies
make test                     # Run tests
uv run uvicorn app.main:app --reload  # Start dev server

# Frontend (Node.js)
cd frontend
npm install                   # Install dependencies
npm run dev                   # Start dev server
npm run generate:api          # Generate API client from OpenAPI
npm run test:e2e              # Run E2E tests

Access points:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Default superuser (change in production):

• Email: admin@example.com
• Password: admin123

Project Architecture

Full-stack TypeScript/Python application:

├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes (auth, users, organizations, admin)
│   │   ├── core/           # Core functionality (auth, config, database)
│   │   ├── crud/           # Database CRUD operations
│   │   ├── models/         # SQLAlchemy ORM models
│   │   ├── schemas/        # Pydantic request/response schemas
│   │   ├── services/       # Business logic layer
│   │   └── utils/          # Utilities (security, device detection)
│   ├── tests/              # 96% coverage, 987 tests
│   └── alembic/            # Database migrations
│
└── frontend/               # Next.js 16 frontend
    ├── src/
    │   ├── app/           # App Router pages (Next.js 16)
    │   ├── components/    # React components
    │   ├── lib/
    │   │   ├── api/       # Auto-generated API client
    │   │   └── stores/    # Zustand state management
    │   └── hooks/         # Custom React hooks
    └── e2e/               # Playwright E2E tests (56 passing)

Critical Implementation Notes

Authentication Flow

• JWT-based: Access tokens (15 min) + refresh tokens (7 days)
• OAuth/Social Login: Google and GitHub with PKCE support
• Session tracking: Database-backed with device info, IP, user agent
• Token refresh: Validates JTI in database, not just JWT signature
• Authorization: FastAPI dependencies in api/dependencies/auth.py
  • get_current_user: Requires valid access token
  • get_current_active_user: Requires active account
  • get_optional_current_user: Accepts authenticated or anonymous
  • get_current_superuser: Requires superuser flag

OAuth Provider Mode (MCP Integration)

Full OAuth 2.0 Authorization Server for MCP (Model Context Protocol) clients:

• Authorization Code Flow with PKCE: RFC 7636 compliant
• JWT access tokens: Self-contained, no DB lookup required
• Opaque refresh tokens: Stored hashed in database, supports rotation
• Token introspection: RFC 7662 compliant endpoint
• Token revocation: RFC 7009 compliant endpoint
• Server metadata: RFC 8414 compliant discovery endpoint
• Consent management: User can review and revoke app permissions

API endpoints:

• GET /.well-known/oauth-authorization-server - Server metadata
• GET /oauth/provider/authorize - Authorization endpoint
• POST /oauth/provider/authorize/consent - Consent submission
• POST /oauth/provider/token - Token endpoint
• POST /oauth/provider/revoke - Token revocation
• POST /oauth/provider/introspect - Token introspection
• Client management endpoints (admin only)

Scopes supported: openid, profile, email, read:users, write:users, admin

OAuth Configuration (backend .env):

# OAuth Social Login (as OAuth Consumer)
OAUTH_ENABLED=true                           # Enable OAuth social login
OAUTH_AUTO_LINK_BY_EMAIL=true                # Auto-link accounts by email
OAUTH_STATE_EXPIRE_MINUTES=10                # CSRF state expiration

# Google OAuth
OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth
OAUTH_GITHUB_CLIENT_ID=your-github-client-id
OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret

# OAuth Provider Mode (as Authorization Server for MCP)
OAUTH_PROVIDER_ENABLED=true                  # Enable OAuth provider mode
OAUTH_ISSUER=https://api.yourdomain.com      # JWT issuer URL (must be HTTPS in production)

Database Pattern

• Async SQLAlchemy 2.0 with PostgreSQL
• Connection pooling: 20 base connections, 50 max overflow
• CRUD base class: crud/base.py with common operations
• Migrations: Alembic with helper script migrate.py
  • python migrate.py auto "message" - Generate and apply
  • python migrate.py list - View history

Frontend State Management

• Zustand stores: Lightweight state management
• TanStack Query: API data fetching/caching
• Auto-generated client: From OpenAPI spec via npm run generate:api
• Dependency Injection: ALWAYS use useAuth() from AuthContext, NEVER import useAuthStore directly

Internationalization (i18n)

• next-intl v4: Type-safe internationalization library
• Locale routing: /en/*, /it/* (English and Italian supported)
• Translation files: frontend/messages/en.json, frontend/messages/it.json
• LocaleSwitcher: Component for seamless language switching
• SEO-friendly: Locale-aware metadata, sitemaps, and robots.txt
• Type safety: Full TypeScript support for translations
• Utilities: frontend/src/lib/i18n/ (metadata, routing, utils)

Organization System

Three-tier RBAC:

• Owner: Full control (delete org, manage all members)
• Admin: Add/remove members, assign admin role (not owner)
• Member: Read-only organization access

Permission dependencies in api/dependencies/permissions.py:

• require_organization_owner
• require_organization_admin
• require_organization_member
• can_manage_organization_member

Testing Infrastructure

Backend Unit/Integration (pytest + SQLite):

• 96% coverage, 987 tests
• Security-focused: JWT attacks, session hijacking, privilege escalation
• Async fixtures in tests/conftest.py
• Run: IS_TEST=True uv run pytest or make test
• Coverage: make test-cov

Backend E2E (pytest + Testcontainers + Schemathesis):

• Real PostgreSQL via Docker containers
• OpenAPI contract testing with Schemathesis
• Install: make install-e2e
• Run: make test-e2e
• Schema tests: make test-e2e-schema
• Docs: backend/docs/E2E_TESTING.md

Frontend Unit Tests (Jest):

• 97% coverage
• Component, hook, and utility testing
• Run: npm test
• Coverage: npm run test:coverage

Frontend E2E Tests (Playwright):

• 56 passing, 1 skipped (zero flaky tests)
• Complete user flows (auth, navigation, settings)
• Run: npm run test:e2e
• UI mode: npm run test:e2e:ui

Development Tooling

Backend:

• uv: Modern Python package manager (10-100x faster than pip)
• Ruff: All-in-one linting/formatting (replaces Black, Flake8, isort)
• mypy: Type checking with Pydantic plugin
• Makefile: make help for all commands

Frontend:

• Next.js 16: App Router with React 19
• TypeScript: Full type safety
• TailwindCSS + shadcn/ui: Design system
• ESLint + Prettier: Code quality

Environment Configuration

Backend (.env):

POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=app

SECRET_KEY=your-secret-key-min-32-chars
ENVIRONMENT=development|production
CSP_MODE=relaxed|strict|disabled

FIRST_SUPERUSER_EMAIL=admin@example.com
FIRST_SUPERUSER_PASSWORD=admin123

BACKEND_CORS_ORIGINS=["http://localhost:3000"]

Frontend (.env.local):

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1

Common Development Workflows

Adding a New API Endpoint

1. Define schema in backend/app/schemas/
2. Create CRUD operations in backend/app/crud/
3. Implement route in backend/app/api/routes/
4. Register router in backend/app/api/main.py
5. Write tests in backend/tests/api/
6. Generate frontend client: npm run generate:api

Database Migrations

cd backend
python migrate.py generate "description"  # Create migration
python migrate.py apply                   # Apply migrations
python migrate.py auto "description"      # Generate + apply

Frontend Component Development

1. Create component in frontend/src/components/
2. Follow design system (see frontend/docs/design-system/)
3. Use dependency injection for auth (useAuth() not useAuthStore)
4. Write tests in frontend/tests/ or __tests__/
5. Run type check: npm run type-check

Security Features

• Password hashing: bcrypt with salt rounds
• Rate limiting: 60 req/min default, 10 req/min on auth endpoints
• Security headers: CSP, X-Frame-Options, HSTS, etc.
• CSRF protection: Built into FastAPI
• Session revocation: Database-backed session tracking
• Comprehensive security tests: JWT algorithm attacks, session hijacking, privilege escalation

Docker Deployment

# Development (with hot reload)
docker-compose -f docker-compose.dev.yml up

# Production
docker-compose up -d

# Run migrations
docker-compose exec backend alembic upgrade head

# Create first superuser
docker-compose exec backend python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"

Documentation

For comprehensive documentation, see:

• README.md - User-facing project overview
• CLAUDE.md - Claude Code-specific guidance
• Backend docs: backend/docs/ (Architecture, Coding Standards, Common Pitfalls, Feature Examples)
• Frontend docs: frontend/docs/ (Design System, Architecture, E2E Testing)
• API docs: http://localhost:8000/docs (Swagger UI when running)

Current Status (Nov 2025)

Completed Features ✅

• Authentication system (JWT with refresh tokens, OAuth/social login)
• OAuth Provider Mode (MCP-ready): Full OAuth 2.0 Authorization Server
• Session management (device tracking, revocation)
• User management (CRUD, password change)
• Organization system (multi-tenant with RBAC)
• Admin panel (user/org management, bulk operations)
• Internationalization (i18n) with English and Italian
• Comprehensive test coverage (96% backend, 97% frontend unit, 56 E2E tests)
• Design system documentation
• Marketing landing page with animations
• /dev documentation portal with live examples
• Toast notifications, charts, markdown rendering
• SEO optimization (sitemap, robots.txt, locale metadata)
• Docker deployment

In Progress 🚧

• Frontend admin pages (70% complete)
• Email integration (templates ready, SMTP pending)

Planned 🔮

• GitHub Actions CI/CD
• Additional languages (Spanish, French, German, etc.)
• SSO/SAML authentication
• Real-time notifications (WebSockets)
• Webhook system
• Background job processing
• File upload/storage