fastapi-fullstack 0.1.2__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/CLAUDE.md

@@ -0,0 +1,357 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**{{ cookiecutter.project_name }}** is a FastAPI application generated with [Full-Stack FastAPI + Next.js Template](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template).
+
+**Stack:**
+- FastAPI + Pydantic v2
+{%- if cookiecutter.use_postgresql %}
+- PostgreSQL (async with asyncpg + SQLAlchemy 2.0)
+{%- endif %}
+{%- if cookiecutter.use_mongodb %}
+- MongoDB (async with motor)
+{%- endif %}
+{%- if cookiecutter.use_sqlite %}
+- SQLite (sync with SQLAlchemy)
+{%- endif %}
+{%- if cookiecutter.use_jwt %}
+- JWT authentication (access + refresh tokens)
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+- Redis (caching, sessions)
+{%- endif %}
+{%- if cookiecutter.enable_ai_agent %}
+- PydanticAI (AI agents with tool support)
+{%- endif %}
+{%- if cookiecutter.use_celery %}
+- Celery (background tasks)
+{%- endif %}
+{%- if cookiecutter.use_taskiq %}
+- Taskiq (async background tasks)
+{%- endif %}
+{%- if cookiecutter.use_frontend %}
+- Next.js 15 + React 19 + TypeScript + Tailwind CSS v4
+{%- endif %}
+
+## Commands
+
+### Backend
+
+```bash
+cd backend
+
+# Install dependencies
+uv sync
+
+# Run development server
+uv run uvicorn app.main:app --reload --port {{ cookiecutter.backend_port }}
+
+# Or use project CLI
+uv run {{ cookiecutter.project_slug }} server run --reload
+
+# Run tests
+pytest
+pytest tests/test_file.py::test_name -v
+
+# Linting and formatting
+ruff check .
+ruff check . --fix
+ruff format .
+
+# Type checking
+mypy app
+```
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+
+### Database
+
+```bash
+cd backend
+
+# Run all migrations
+uv run alembic upgrade head
+
+# Create new migration
+uv run alembic revision --autogenerate -m "Description"
+
+# Or use project CLI
+uv run {{ cookiecutter.project_slug }} db upgrade
+uv run {{ cookiecutter.project_slug }} db migrate -m "Description"
+```
+{%- endif %}
+{%- if cookiecutter.use_jwt %}
+
+### User Management
+
+```bash
+cd backend
+
+# Create admin user
+uv run {{ cookiecutter.project_slug }} user create-admin --email admin@example.com
+
+# List users
+uv run {{ cookiecutter.project_slug }} user list
+```
+{%- endif %}
+{%- if cookiecutter.use_frontend %}
+
+### Frontend
+
+```bash
+cd frontend
+
+# Install dependencies
+bun install
+
+# Run development server
+bun dev
+
+# Run tests
+bun test
+bun test:e2e
+```
+{%- endif %}
+{%- if cookiecutter.enable_docker %}
+
+### Docker
+
+```bash
+# Start all services
+docker compose up -d
+
+# View logs
+docker compose logs -f
+
+# Stop services
+docker compose down
+```
+{%- endif %}
+
+## Architecture
+
+This project follows a **Repository + Service** layered architecture:
+
+```
+API Routes → Services → Repositories → Database
+```
+
+### Directory Structure (`backend/app/`)
+
+| Directory | Purpose |
+|-----------|---------|
+| `api/routes/v1/` | HTTP endpoints, request validation, auth |
+| `api/deps.py` | Dependency injection (db session, current user) |
+| `services/` | Business logic, orchestration |
+| `repositories/` | Data access layer, database queries |
+| `schemas/` | Pydantic models for request/response |
+| `db/models/` | SQLAlchemy/MongoDB models |
+| `core/config.py` | Settings via pydantic-settings |
+{%- if cookiecutter.use_auth %}
+| `core/security.py` | JWT/API key utilities |
+{%- endif %}
+{%- if cookiecutter.enable_ai_agent %}
+| `agents/` | PydanticAI agents and tools |
+{%- endif %}
+| `commands/` | Django-style CLI commands |
+{%- if cookiecutter.use_celery or cookiecutter.use_taskiq %}
+| `worker/` | Background task definitions |
+{%- endif %}
+
+### Adding New Features
+
+**1. Add a new API endpoint:**
+```
+1. Create schema in `schemas/`
+2. Create model in `db/models/` (if new entity)
+3. Create repository in `repositories/`
+4. Create service in `services/`
+5. Create route in `api/routes/v1/`
+6. Register route in `api/routes/v1/__init__.py`
+```
+
+**2. Add a custom CLI command:**
+```python
+# app/commands/my_command.py
+from app.commands import command, success
+import click
+
+@command("my-command", help="Description")
+@click.option("--option", "-o", help="Some option")
+def my_command(option: str):
+    # Logic here
+    success(f"Done with {option}")
+```
+Commands are auto-discovered. Run with: `{{ cookiecutter.project_slug }} cmd my-command`
+{%- if cookiecutter.enable_ai_agent %}
+
+**3. Add an AI agent tool:**
+```python
+# app/agents/assistant.py
+@agent.tool
+async def my_tool(ctx: RunContext[Deps], param: str) -> dict:
+    """Tool description for LLM."""
+    # Tool logic
+    return {"result": param}
+```
+{%- endif %}
+
+## Key Patterns
+
+### Dependency Injection
+
+```python
+# In routes
+from app.api.deps import get_db, get_current_user
+
+@router.get("/items")
+async def list_items(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    service = ItemService(db)
+    return await service.get_multi()
+```
+
+### Service Layer
+
+```python
+# Services contain business logic
+class ItemService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def create(self, item_in: ItemCreate) -> Item:
+        # Business validation
+        # Repository calls
+        return await item_repo.create(self.db, **item_in.model_dump())
+```
+
+### Repository Layer
+
+```python
+# Repositories handle data access only
+class ItemRepository:
+    async def get_by_id(self, db: AsyncSession, id: UUID) -> Item | None:
+        return await db.get(Item, id)
+
+    async def create(self, db: AsyncSession, **kwargs) -> Item:
+        item = Item(**kwargs)
+        db.add(item)
+        await db.flush()
+        await db.refresh(item)
+        return item
+```
+
+### Custom Exceptions
+
+```python
+from app.core.exceptions import NotFoundError, AlreadyExistsError
+
+# In services
+if not item:
+    raise NotFoundError(message="Item not found", details={"id": str(id)})
+```
+{%- if cookiecutter.use_frontend %}
+
+## Frontend Patterns
+
+### Authentication
+
+Tokens stored in HTTP-only cookies. Use the auth hook:
+
+```typescript
+import { useAuth } from '@/hooks/use-auth';
+
+function Component() {
+  const { user, isAuthenticated, login, logout } = useAuth();
+}
+```
+
+### State Management (Zustand)
+
+```typescript
+import { useAuthStore } from '@/stores/auth-store';
+
+const { user, setUser, logout } = useAuthStore();
+```
+{%- if cookiecutter.enable_ai_agent %}
+
+### WebSocket Chat
+
+```typescript
+import { useChat } from '@/hooks/use-chat';
+
+function ChatPage() {
+  const { messages, sendMessage, isStreaming } = useChat();
+}
+```
+{%- endif %}
+{%- endif %}
+
+## Environment Variables
+
+Key variables in `.env`:
+
+```bash
+ENVIRONMENT=local  # local, staging, production
+{%- if cookiecutter.use_postgresql %}
+POSTGRES_HOST=localhost
+POSTGRES_PASSWORD=secret
+{%- endif %}
+{%- if cookiecutter.use_jwt %}
+SECRET_KEY=change-me-use-openssl-rand-hex-32
+{%- endif %}
+{%- if cookiecutter.enable_ai_agent %}
+OPENAI_API_KEY=sk-...
+{%- endif %}
+{%- if cookiecutter.enable_logfire %}
+LOGFIRE_TOKEN=your-token
+{%- endif %}
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# With coverage
+pytest --cov=app --cov-report=term-missing
+
+# Specific test
+pytest tests/api/test_health.py -v
+
+# Run only unit tests
+pytest tests/unit/
+
+# Run only integration tests
+pytest tests/integration/
+```
+
+## Key Design Decisions
+
+{%- if cookiecutter.use_postgresql or cookiecutter.use_mongodb %}
+- Database operations are async
+{%- endif %}
+- Use `db.flush()` in repositories (not `commit`) - let the dependency manage transactions
+- Services raise domain exceptions (`NotFoundError`, etc.) - routes convert to HTTP
+- Schemas are separate for Create, Update, and Response
+{%- if cookiecutter.enable_ai_agent %}
+- AI Agent uses `iter()` for WebSocket streaming (not `run()`)
+{%- endif %}
+- Custom commands auto-discovered from `app/commands/`
+
+## Documentation
+
+- [Template Repository](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template)
+- [Architecture Guide](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template/blob/main/docs/architecture.md)
+{%- if cookiecutter.use_frontend %}
+- [Frontend Guide](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template/blob/main/docs/frontend.md)
+{%- endif %}
+{%- if cookiecutter.enable_ai_agent %}
+- [AI Agent Guide](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template/blob/main/docs/ai-agent.md)
+{%- endif %}
+- [Deployment Guide](https://github.com/vstorm-co/full-stack-fastapi-nextjs-llm-template/blob/main/docs/deployment.md)

fastapi_gen/template/{{cookiecutter.project_slug}}/Makefile

@@ -0,0 +1,298 @@
+.PHONY: install format lint test run clean help db-init
+
+# === Setup ===
+install:
+	uv sync --directory backend --dev
+{%- if cookiecutter.enable_precommit %}
+	uv run --directory backend pre-commit install
+{%- endif %}
+	@echo ""
+	@echo "✅ Installation complete!"
+	@echo "Next steps:"
+	@echo "  1. cp .env.example .env"
+	@echo "  2. Edit .env with your settings"
+{%- if cookiecutter.use_postgresql %}
+	@echo "  3. make docker-db"
+	@echo "  4. make db-migrate && make db-upgrade"
+{%- endif %}
+	@echo "  5. make run"
+
+# === Code Quality ===
+format:
+	uv run --directory backend ruff format app tests cli
+	uv run --directory backend ruff check app tests cli --fix
+
+lint:
+	uv run --directory backend ruff check app tests cli
+	uv run --directory backend ruff format app tests cli --check
+	uv run --directory backend mypy app
+
+# === Testing ===
+test:
+	uv run --directory backend pytest tests/ -v
+
+test-cov:
+	uv run --directory backend pytest tests/ -v --cov=app --cov-report=html --cov-report=term-missing
+
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+
+# === Database ===
+{%- if cookiecutter.use_postgresql and cookiecutter.enable_docker %}
+db-init: docker-db
+	@echo "Waiting for PostgreSQL to be ready..."
+	@sleep 3
+	uv run --directory backend {{ cookiecutter.project_slug }} db upgrade
+	@echo ""
+	@echo "✅ Database initialized!"
+{%- else %}
+db-init:
+	uv run --directory backend {{ cookiecutter.project_slug }} db upgrade
+	@echo ""
+	@echo "✅ Database initialized!"
+{%- endif %}
+
+db-migrate:
+	@read -p "Migration message: " msg; \
+	uv run --directory backend {{ cookiecutter.project_slug }} db migrate -m "$$msg"
+
+db-upgrade:
+	uv run --directory backend {{ cookiecutter.project_slug }} db upgrade
+
+db-downgrade:
+	uv run --directory backend {{ cookiecutter.project_slug }} db downgrade
+
+db-current:
+	uv run --directory backend {{ cookiecutter.project_slug }} db current
+
+db-history:
+	uv run --directory backend {{ cookiecutter.project_slug }} db history
+{%- endif %}
+
+# === Server ===
+run:
+	uv run --directory backend {{ cookiecutter.project_slug }} server run --reload
+
+run-prod:
+	uv run --directory backend {{ cookiecutter.project_slug }} server run --host 0.0.0.0 --port 8000
+
+routes:
+	uv run --directory backend {{ cookiecutter.project_slug }} server routes
+
+{%- if cookiecutter.use_jwt %}
+
+# === Users ===
+user-create:
+	uv run --directory backend {{ cookiecutter.project_slug }} user create
+
+user-list:
+	uv run --directory backend {{ cookiecutter.project_slug }} user list
+{%- endif %}
+
+{%- if cookiecutter.use_celery %}
+
+# === Celery ===
+celery-worker:
+	uv run --directory backend {{ cookiecutter.project_slug }} celery worker
+
+celery-beat:
+	uv run --directory backend {{ cookiecutter.project_slug }} celery beat
+
+celery-flower:
+	uv run --directory backend {{ cookiecutter.project_slug }} celery flower
+	@echo ""
+	@echo "✅ Flower started at http://localhost:5555"
+{%- endif %}
+
+{%- if cookiecutter.use_taskiq %}
+
+# === Taskiq ===
+taskiq-worker:
+	uv run --directory backend {{ cookiecutter.project_slug }} taskiq worker
+
+taskiq-scheduler:
+	uv run --directory backend {{ cookiecutter.project_slug }} taskiq scheduler
+{%- endif %}
+
+{%- if cookiecutter.enable_docker %}
+
+# === Docker: Backend (Development) ===
+docker-up:
+	docker-compose up -d
+	@echo ""
+	@echo "✅ Backend services started!"
+	@echo "   API: http://localhost:{{ cookiecutter.backend_port }}"
+	@echo "   Docs: http://localhost:{{ cookiecutter.backend_port }}/docs"
+{%- if cookiecutter.use_celery %}
+	@echo "   Flower: http://localhost:5555"
+{%- endif %}
+{%- if cookiecutter.use_postgresql %}
+	@echo "   PostgreSQL: localhost:5432"
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+	@echo "   Redis: localhost:6379"
+{%- endif %}
+
+docker-down:
+	docker-compose down
+{%- if cookiecutter.use_frontend %}
+	docker-compose -f docker-compose.frontend.yml down 2>/dev/null || true
+{%- endif %}
+
+docker-logs:
+	docker-compose logs -f
+
+docker-build:
+	docker-compose build
+
+docker-shell:
+	docker-compose exec app /bin/bash
+
+{%- if cookiecutter.use_frontend %}
+
+# === Docker: Frontend (Development) ===
+docker-frontend:
+	docker-compose -f docker-compose.frontend.yml up -d
+	@echo ""
+	@echo "✅ Frontend started!"
+	@echo "   URL: http://localhost:{{ cookiecutter.frontend_port }}"
+	@echo ""
+	@echo "Note: Backend must be running (make docker-up)"
+
+docker-frontend-down:
+	docker-compose -f docker-compose.frontend.yml down
+
+docker-frontend-logs:
+	docker-compose -f docker-compose.frontend.yml logs -f
+
+docker-frontend-build:
+	docker-compose -f docker-compose.frontend.yml build
+{%- endif %}
+
+# === Docker: Production (with Traefik) ===
+docker-prod:
+	docker-compose -f docker-compose.prod.yml up -d
+	@echo ""
+	@echo "✅ Production services started with Traefik!"
+	@echo ""
+	@echo "Endpoints (replace DOMAIN with your domain):"
+{%- if cookiecutter.use_frontend %}
+	@echo "   Frontend: https://$$DOMAIN"
+{%- endif %}
+	@echo "   API: https://api.$$DOMAIN"
+{%- if cookiecutter.use_celery %}
+	@echo "   Flower: https://flower.$$DOMAIN"
+{%- endif %}
+	@echo "   Traefik: https://traefik.$$DOMAIN"
+
+docker-prod-down:
+	docker-compose -f docker-compose.prod.yml down
+
+docker-prod-logs:
+	docker-compose -f docker-compose.prod.yml logs -f
+
+docker-prod-build:
+	docker-compose -f docker-compose.prod.yml build
+
+{%- if cookiecutter.use_postgresql %}
+
+# === Docker: Individual Services ===
+docker-db:
+	docker-compose up -d db
+	@echo ""
+	@echo "✅ PostgreSQL started on port 5432"
+	@echo "   Connection: postgresql://postgres:postgres@localhost:5432/{{ cookiecutter.project_slug }}"
+
+docker-db-stop:
+	docker-compose stop db
+{%- endif %}
+
+{%- if cookiecutter.enable_redis %}
+
+docker-redis:
+	docker-compose up -d redis
+	@echo ""
+	@echo "✅ Redis started on port 6379"
+
+docker-redis-stop:
+	docker-compose stop redis
+{%- endif %}
+{%- endif %}
+
+# === Cleanup ===
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	rm -rf htmlcov/ .coverage coverage.xml
+
+# === Help ===
+help:
+	@echo ""
+	@echo "{{ cookiecutter.project_name }} - Available Commands"
+	@echo "======================================"
+	@echo ""
+	@echo "Setup:"
+	@echo "  make install       Install dependencies + pre-commit hooks"
+	@echo ""
+	@echo "Development:"
+	@echo "  make run           Start dev server (with hot reload)"
+	@echo "  make test          Run tests"
+	@echo "  make lint          Check code quality"
+	@echo "  make format        Auto-format code"
+	@echo ""
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+	@echo "Database:"
+	@echo "  make db-init       Initialize database (start + migrate)"
+	@echo "  make db-migrate    Create new migration"
+	@echo "  make db-upgrade    Apply migrations"
+	@echo "  make db-downgrade  Rollback last migration"
+	@echo "  make db-current    Show current migration"
+	@echo ""
+{%- endif %}
+{%- if cookiecutter.use_jwt %}
+	@echo "Users:"
+	@echo "  make user-create   Create new user (interactive)"
+	@echo "  make user-list     List all users"
+	@echo ""
+{%- endif %}
+{%- if cookiecutter.use_celery %}
+	@echo "Celery:"
+	@echo "  make celery-worker  Start Celery worker"
+	@echo "  make celery-beat    Start Celery beat scheduler"
+	@echo "  make celery-flower  Start Flower monitoring UI"
+	@echo ""
+{%- endif %}
+{%- if cookiecutter.use_taskiq %}
+	@echo "Taskiq:"
+	@echo "  make taskiq-worker     Start Taskiq worker"
+	@echo "  make taskiq-scheduler  Start Taskiq scheduler"
+	@echo ""
+{%- endif %}
+{%- if cookiecutter.enable_docker %}
+	@echo "Docker (Development):"
+	@echo "  make docker-up            Start backend services"
+	@echo "  make docker-down          Stop all services"
+	@echo "  make docker-logs          View backend logs"
+	@echo "  make docker-build         Build backend images"
+{%- if cookiecutter.use_frontend %}
+	@echo "  make docker-frontend      Start frontend (separate)"
+	@echo "  make docker-frontend-down Stop frontend"
+{%- endif %}
+{%- if cookiecutter.use_postgresql %}
+	@echo "  make docker-db            Start only PostgreSQL"
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+	@echo "  make docker-redis         Start only Redis"
+{%- endif %}
+	@echo ""
+	@echo "Docker (Production with Traefik):"
+	@echo "  make docker-prod          Start production stack"
+	@echo "  make docker-prod-down     Stop production stack"
+	@echo "  make docker-prod-logs     View production logs"
+	@echo ""
+{%- endif %}
+	@echo "Other:"
+	@echo "  make routes        Show all API routes"
+	@echo "  make clean         Clean cache files"
+	@echo ""