full-stack-ai-agent-template: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Full-Stack AI Agent Template is an interactive CLI tool that generates production-ready FastAPI + Next.js projects with AI agents, RAG, and 20+ enterprise integrations. Uses Cookiecutter templates with Jinja2 conditionals.

Commands

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run single test
uv run pytest tests/test_file.py::test_name -v

# Linting and formatting
uv run ruff check . --fix
uv run ruff format .

# Type checking
uv run ty check

CLI Usage

# Interactive wizard (default)
fastapi-fullstack

# Quick project creation
fastapi-fullstack create my_project --database postgresql

# With RAG
fastapi-fullstack create my_project --ai-framework pydantic_ai --rag --database postgresql --task-queue celery

# List available options
fastapi-fullstack templates

Architecture

Core Modules (fastapi_gen/)

• cli.py - Click-based CLI: new (interactive, default), create (direct), templates (list options)
• config.py - Pydantic models: ProjectConfig, enums (AIFrameworkType, LLMProviderType, VectorStoreType, etc.), validation, cookiecutter context
• prompts.py - Questionary-based interactive prompts → ProjectConfig
• generator.py - Cookiecutter invocation and post-generation messaging

Template System (template/)

template/
├── cookiecutter.json                    # Default context (~120 variables)
├── hooks/post_gen_project.py            # Post-gen cleanup & formatting
└── {{cookiecutter.project_slug}}/
    ├── backend/
    │   ├── app/
    │   │   ├── main.py                  # FastAPI app with lifespan
    │   │   ├── api/                     # Routes, deps, exception handlers
    │   │   ├── core/                    # Config, security, middleware
    │   │   ├── db/                      # Models, session management
    │   │   ├── schemas/                 # Pydantic request/response models
    │   │   ├── repositories/            # Data access layer
    │   │   ├── services/               # Business logic
    │   │   ├── agents/                  # AI agents (5 frameworks)
    │   │   ├── rag/                     # RAG module (4 vector stores, embeddings, sources)
    │   │   │   └── connectors/          # Sync source connectors (Google Drive, S3)
    │   │   ├── commands/                # Django-style CLI commands
    │   │   └── worker/                  # Background tasks (Celery/Taskiq/ARQ)
    │   ├── cli/                         # Generated project CLI
    │   └── alembic/                     # Migrations (if SQL DB)
    └── frontend/                        # Next.js 15 (optional)
        └── src/
            ├── app/[locale]/            # i18n-routed pages (PL/EN)
            │   ├── (marketing)/         # Public pages (home, pricing, blog, legal)
            │   ├── (auth)/              # Login, register, reset-password
            │   ├── chat/, kb/, settings/, admin/
            │   └── auth/magic-link/     # Magic-link verify
            ├── components/
            │   ├── marketing/           # Hero, features, pricing, FAQ, CTAs
            │   ├── legal/               # privacy/terms/cookies content (per-locale)
            │   ├── auth/, chat/, kb/, settings/, dashboard/, admin/
            │   └── ui/                  # shadcn-style primitives
            └── app/{icon,opengraph-image,manifest,robots,sitemap}.tsx