Document AI assistant guidance and improve developer workflows
- Added and updated `CLAUDE.md` to provide comprehensive guidance for integrating Claude Code into project workflows. - Created `AGENTS.md` for general AI assistant context, including architecture, workflows, and tooling specifics. - Updated `README.md` with references to AI-focused documentation for better discoverability. - Simplified instructions and refined file organization to enhance usability for developers and AI assistants.
This commit is contained in:
Felipe Cardoso
242
AGENTS.md
Normal file
242
AGENTS.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 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
|
||||
|
||||
### 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 (pytest):**
|
||||
- 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`
|
||||
- Coverage: `IS_TEST=True uv run pytest --cov=app --cov-report=term-missing`
|
||||
|
||||
**Frontend Unit Tests (Jest):**
|
||||
- 97% coverage
|
||||
- Component, hook, and utility testing
|
||||
- Run: `npm test`
|
||||
- Coverage: `npm run test:coverage`
|
||||
|
||||
**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)
|
||||
- Comprehensive test coverage (97% backend, 97% frontend unit, 56 E2E tests)
|
||||
- Design system documentation
|
||||
- Docker deployment
|
||||
|
||||
### In Progress 🚧
|
||||
- Frontend admin pages (70% complete)
|
||||
- Dark mode theme
|
||||
- Email integration (templates ready, SMTP pending)
|
||||
|
||||
### Planned 🔮
|
||||
- GitHub Actions CI/CD
|
||||
- Additional authentication methods (OAuth, SSO)
|
||||
- Webhook system
|
||||
- Background job processing
|
||||
- File upload/storage
|
||||
- Notification system
|
||||
Reference in New Issue
Block a user