forked from cardosofelipe/fast-next-template
29074f26a6
- Deleted `I18N_IMPLEMENTATION_PLAN.md` and `PROJECT_PROGRESS.md` to declutter the repository. - These documents were finalized, no longer relevant, and superseded by implemented features and external references.
308 lines
11 KiB
Markdown
308 lines
11 KiB
Markdown
# AGENTS.md
|
|
|
|
AI coding assistant context for FastAPI + Next.js Full-Stack Template.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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`):**
|
|
```bash
|
|
# 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`):
|
|
```bash
|
|
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`):
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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](./README.md)** - User-facing project overview
|
|
- **[CLAUDE.md](./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
|