# AI Assistant - Project Conventions

## Tech Stack

- **Backend**: Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, Pydantic v2
- **Frontend**: React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui, Zustand, TanStack Query
- **Database**: PostgreSQL 16
- **AI**: Claude API (Anthropic SDK) with streaming + tool use
- **Deployment**: Docker Compose (nginx, backend, frontend, postgres, redis)

## Project Structure

```
backend/
  app/
    api/v1/         # FastAPI routers (thin controllers)
    core/           # Security, middleware, logging, exceptions
    models/         # SQLAlchemy ORM models (inherit from Base in database.py)
    schemas/        # Pydantic request/response models
    services/       # Business logic layer
    utils/          # Utilities (file storage, text extraction)
    workers/        # Background tasks (document processing, notifications)
    templates/      # Jinja2 templates (PDF generation)
  alembic/          # Database migrations
  scripts/          # Standalone scripts (seed_admin.py)
  tests/            # Pytest test files

frontend/
  src/
    api/            # Axios API client modules
    components/     # React components (layout/, chat/, auth/, shared/, etc.)
    hooks/          # Custom React hooks
    stores/         # Zustand state stores
    pages/          # Page components (mapped to routes)
    lib/            # Utilities (cn(), query-client)
```

## Adding a New Feature (Endpoint to UI)

1. **Model**: Create in `backend/app/models/`, inherit `Base` from `database.py`
2. **Migration**: `alembic revision -m "description"` or write manually in `alembic/versions/`
3. **Schema**: Create Pydantic models in `backend/app/schemas/`
4. **Service**: Business logic in `backend/app/services/`
5. **Router**: FastAPI endpoint in `backend/app/api/v1/`, register in `router.py`
6. **Frontend API**: Typed functions in `frontend/src/api/`
7. **Page/Component**: React component in `frontend/src/pages/` or `components/`
8. **Route**: Add to `frontend/src/routes.tsx`
9. **i18n**: Add keys to both `public/locales/en/` and `ru/translation.json`
10. **Tests**: Add to `backend/tests/`

## Conventions

- **Auth**: JWT access (15min) + refresh (24h/30d) tokens. Use `get_current_user` dependency.
- **Admin**: Use `require_admin` dependency. All admin endpoints under `/api/v1/admin/`.
- **Ownership**: Always filter by `user_id` — never expose other users' data.
- **Schemas**: Use `model_config = {"from_attributes": True}` for ORM compatibility.
- **JSONB columns**: Name the Python attribute `metadata_` with `mapped_column("metadata", JSONB)`.
- **Error responses**: Use `HTTPException` or `AppException` subclasses.
- **i18n**: All user-facing strings via `useTranslation()`. Both `en` and `ru` required.
- **State**: Zustand for client state, TanStack Query for server state.
- **Sidebar nav**: Add to `navItems` array in `sidebar.tsx`.

## Running

```bash
# Development
cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Production
cp .env.production.example .env
docker compose up -d --build

# Seed admin user
docker compose exec backend python scripts/seed_admin.py

# Run backend tests (requires test DB)
docker compose exec backend pytest
```

## Environment Variables

See `.env.example` for development and `.env.production.example` for production.