cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/fast-next-template
Code Issues 18 Pull Requests Wiki Activity
Files
c0b253a01021f1a89e8071d63b8c50fc7623b11f
syndarix/AGENTS.md
Felipe Cardoso c0b253a010 Add support for E2E testing infrastructure and OAuth configurations 
- Introduced make commands for E2E tests using Testcontainers and Schemathesis.
- Updated `.env.demo` with configurable OAuth settings for Google and GitHub.
- Enhanced `README.md` with updated environment setup instructions.
- Added E2E testing dependencies and markers in `pyproject.toml` for real PostgreSQL and API contract validation.
- Included new libraries (`arrow`, `attrs`, `docker`, etc.) for testing and schema validation workflows.
2025-11-25 22:24:23 +01:00

265 lines
9.0 KiB
Markdown
Raw Blame History

# 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/ # 97% coverage, 743 tests
│ └── alembic/ # Database migrations
│
└── frontend/ # Next.js 15 frontend
├── src/
│ ├── app/ # App Router pages (Next.js 15)
│ ├── 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)
- **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
### 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):**
- 97% coverage, 743+ 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 15**: 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)
- 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 (97% 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.)
- Additional authentication methods (OAuth, SSO)
- Real-time notifications (WebSockets)
- Webhook system
- Background job processing
- File upload/storage
Reference in New Issue View Git Blame Copy Permalink