dreamweaver/AGENTS.md

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

# 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.tasks worker --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

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
• Proxy in dev: Vite proxies /api, /auth, /admin to backend (see vite.config.ts)

Provider System

AI providers are configured via env vars (TEXT_PROVIDERS, IMAGE_PROVIDERS, TTS_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 (JSON arrays)
• 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/session	Get current user
POST	/api/generate	Generate/enhance story
POST	/api/image/generate/{id}	Generate cover image
GET	/api/audio/{id}	Get TTS audio
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)