# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

## Project Overview

DreamWeaver (梦语织机) - AI-powered children's story generation app for ages 3-8. Features story generation from keywords, story enhancement, AI-generated cover images, and text-to-speech narration.

**Language:** Chinese (Simplified) for UI and comments.

## Tech Stack

- **Backend:** FastAPI + PostgreSQL (Neon) + SQLAlchemy (async) + Celery/Redis | **Python 3.11+**
- **Frontend:** Vue 3 + TypeScript + Pinia + Tailwind CSS + vue-i18n
- **Auth:** OAuth 2.0 (GitHub/Google) with JWT in httpOnly cookie
- **AI Services:** Text generation, image generation, TTS (pluggable adapters)

## Commands

```bash
# Docker demo stack
cp backend/.env.example backend/.env
docker compose up -d --build
docker compose ps

# Backend
cd backend
pip install -e .                              # Install dependencies
pip install -e ".[dev]"                       # With dev tools (pytest, ruff)
uvicorn app.main:app --reload --port 8000     # Start dev server

# Celery worker (requires Redis)
celery -A app.core.celery_app worker --loglevel=info
celery -A app.core.celery_app beat --loglevel=info

# Database migrations
alembic upgrade head                          # Run migrations
alembic revision -m "message" --autogenerate  # Generate new migration

# Linting
ruff check app/                               # Check code
ruff check app/ --fix                         # Auto-fix

# Testing
pytest                                        # Run all tests
pytest tests/test_auth.py -v                  # Single test file
pytest -k "test_name"                         # Match pattern

# Frontend
cd frontend
npm install
npm run dev                                   # Start dev server (port 5173)
npm run build                                 # Type-check + build

# Admin frontend
cd admin-frontend
npm install
npm run dev
npm run build
```

## Architecture

```
backend/app/
├── main.py                    # FastAPI app entry, routes registration
├── api/
│   ├── auth.py                # OAuth routes (GitHub/Google)
│   ├── stories.py             # Story CRUD and AI generation endpoints
│   ├── profiles.py            # User profile management
│   ├── universes.py           # Story universe/world management
│   ├── reading_events.py      # Reading progress tracking
│   ├── push_configs.py        # Push notification settings
│   ├── admin_providers.py     # Provider CRUD (admin)
│   └── admin_reload.py        # Hot-reload providers (admin)
├── core/
│   ├── config.py              # Pydantic settings from env
│   ├── deps.py                # Dependency injection (auth, db session)
│   ├── security.py            # JWT token create/verify
│   ├── prompts.py             # AI prompt templates
│   └── admin_auth.py          # Basic Auth for admin routes
├── db/
│   ├── database.py            # SQLAlchemy async engine + session
│   ├── models.py              # User, Story models
│   └── admin_models.py        # Provider model
├── services/
│   ├── adapters/              # Capability adapters (text, image, tts)
│   ├── provider_router.py     # Failover routing across providers
│   ├── provider_cache.py      # In-memory provider config cache
│   ├── provider_metrics.py    # Provider performance metrics
│   └── achievement_extractor.py  # Extract achievements from stories
└── tasks/
    ├── achievements.py        # Celery task: achievement processing
    └── push_notifications.py  # Celery task: push notifications

frontend/src/
├── api/client.ts              # Axios wrapper with auth interceptors
├── stores/user.ts             # Pinia user state
├── router.ts                  # Vue Router config
├── i18n.ts + locales/         # vue-i18n setup
├── components/                # Reusable Vue components
└── views/                     # Page components
```

## Key Patterns

- **Async everywhere:** All database and API calls use async/await
- **Dependency injection:** FastAPI `Depends()` for auth and db session
- **JWT auth:** Stored in httpOnly cookie, validated via `get_current_user` dependency
- **Provider routing:** `provider_router.py` tries providers in order, auto-failover on error
- **Background tasks:** Celery workers handle achievements and push notifications
- **Docker proxy:** Frontend Nginx proxies `/api`, `/auth`, `/admin`, `/static` to backend services
- **Local demo:** `ENABLE_DEMO_PROVIDERS=true` enables deterministic text/image/storybook demo adapters

## Provider System

AI providers are configured via env vars (`TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS`, `STORYBOOK_PROVIDERS`) as JSON arrays. The router tries each in order and fails over automatically.

Admin console (disabled by default): Set `ENABLE_ADMIN_CONSOLE=true` to enable `/admin/providers` CRUD endpoints with Basic Auth (`ADMIN_USERNAME`/`ADMIN_PASSWORD`).

## Environment Variables

See `backend/.env.example` for required variables:

- `DATABASE_URL`, `SECRET_KEY` (required)
- OAuth: `GITHUB_CLIENT_ID/SECRET`, `GOOGLE_CLIENT_ID/SECRET`
- AI: `TEXT_API_KEY`, `TTS_API_BASE`, `TTS_API_KEY`, `IMAGE_API_KEY`
- Providers: `TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS`, `STORYBOOK_PROVIDERS` (JSON arrays)
- Demo mode: `ENABLE_DEMO_PROVIDERS`
- Celery: `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND` (Redis URLs)
- Admin: `ENABLE_ADMIN_CONSOLE`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`

## API Endpoints

| Method              | Route                      | Description                 |
| ------------------- | -------------------------- | --------------------------- |
| GET                 | `/auth/{provider}/signin`  | OAuth login                 |
| GET                 | `/auth/dev/signin`         | Local dev login             |
| GET                 | `/auth/session`            | Get current user            |
| POST                | `/api/generations`         | Unified story/storybook generation |
| GET                 | `/api/generations/{id}`    | Get generated result        |
| POST                | `/api/generations/{id}/retry-assets` | Retry generated assets |
| GET                 | `/api/stories`             | List stories (paginated)    |
| GET/DELETE          | `/api/stories/{id}`        | Story CRUD                  |
| CRUD                | `/api/profiles`            | User profiles               |
| CRUD                | `/api/universes`           | Story universes             |
| CRUD                | `/api/reading-events`      | Reading progress            |
| CRUD                | `/api/push-configs`        | Push notification settings  |
| GET/POST/PUT/DELETE | `/admin/providers`         | Provider management (admin) |
| GET                 | `/admin/providers/capabilities` | Provider capability policy |