pragma-stack: Instructions file for Codex

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
bun install                   # Install dependencies
bun run dev                   # Start dev server
bun run generate:api          # Generate API client from OpenAPI
bun 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: [email protected]
• 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)
│   │   ├── repositories/   # Repository pattern (database 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