fastapi-fullstack 0.1.7__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/docs/adding_features.md

@@ -0,0 +1,132 @@
+# Adding New Features
+
+## Adding a New API Endpoint
+
+1. **Create schema** in `schemas/`
+   ```python
+   # schemas/item.py
+   class ItemCreate(BaseModel):
+       name: str
+       description: str | None = None
+
+   class ItemResponse(BaseModel):
+       id: UUID
+       name: str
+       created_at: datetime
+   ```
+
+2. **Create model** in `db/models/` (if new entity)
+   ```python
+   # db/models/item.py
+   class Item(Base):
+       __tablename__ = "items"
+       id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+       name: Mapped[str] = mapped_column(String(255))
+   ```
+
+3. **Create repository** in `repositories/`
+   ```python
+   # repositories/item.py
+   class ItemRepository:
+       async def create(self, db: AsyncSession, **kwargs) -> Item:
+           item = Item(**kwargs)
+           db.add(item)
+           await db.flush()
+           await db.refresh(item)
+           return item
+   ```
+
+4. **Create service** in `services/`
+   ```python
+   # services/item.py
+   class ItemService:
+       def __init__(self, db: AsyncSession):
+           self.db = db
+           self.repo = ItemRepository()
+
+       async def create(self, item_in: ItemCreate) -> Item:
+           return await self.repo.create(self.db, **item_in.model_dump())
+   ```
+
+5. **Create route** in `api/routes/v1/`
+   ```python
+   # api/routes/v1/items.py
+   router = APIRouter(prefix="/items", tags=["items"])
+
+   @router.post("/", response_model=ItemResponse, status_code=201)
+   async def create_item(
+       item_in: ItemCreate,
+       db: AsyncSession = Depends(get_db),
+   ):
+       service = ItemService(db)
+       return await service.create(item_in)
+   ```
+
+6. **Register route** in `api/routes/v1/__init__.py`
+   ```python
+   from .items import router as items_router
+   api_router.include_router(items_router)
+   ```
+
+## Adding a Custom CLI Command
+
+Commands are auto-discovered from `app/commands/`.
+
+```python
+# app/commands/my_command.py
+from app.commands import command, success, error
+import click
+
+@command("my-command", help="Description of what this does")
+@click.option("--name", "-n", required=True, help="Name parameter")
+def my_command(name: str):
+    # Your logic here
+    success(f"Done: {name}")
+```
+
+Run with: `uv run {{ cookiecutter.project_slug }} cmd my-command --name test`
+{%- if cookiecutter.enable_ai_agent and cookiecutter.use_pydantic_ai %}
+
+## Adding an AI Agent Tool (PydanticAI)
+
+```python
+# app/agents/assistant.py
+@agent.tool
+async def my_tool(ctx: RunContext[Deps], param: str) -> dict:
+    """Tool description for LLM - be specific about what it does."""
+    # Access dependencies via ctx.deps
+    result = await some_operation(param)
+    return {"result": result}
+```
+{%- endif %}
+{%- if cookiecutter.enable_ai_agent and cookiecutter.use_langchain %}
+
+## Adding an AI Agent Tool (LangChain)
+
+```python
+# app/agents/langchain_assistant.py
+from langchain.tools import tool
+
+@tool
+def my_tool(param: str) -> dict:
+    """Tool description for LLM - be specific about what it does."""
+    result = some_operation(param)
+    return {"result": result}
+```
+{%- endif %}
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite %}
+
+## Adding a Database Migration
+
+```bash
+# Create migration
+uv run alembic revision --autogenerate -m "Add items table"
+
+# Apply migration
+uv run alembic upgrade head
+
+# Or use CLI
+uv run {{ cookiecutter.project_slug }} db migrate -m "Add items table"
+uv run {{ cookiecutter.project_slug }} db upgrade
+```
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/docs/architecture.md

@@ -0,0 +1,63 @@
+# Architecture Guide
+
+This project follows a **Repository + Service** layered architecture.
+
+## Request Flow
+
+```
+HTTP Request → API Route → Service → Repository → Database
+                  ↓
+              Response ← Service ← Repository ←
+```
+
+## 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/` | AI agents and tools |
+{%- endif %}
+| `commands/` | Django-style CLI commands |
+{%- if cookiecutter.use_celery or cookiecutter.use_taskiq %}
+| `worker/` | Background task definitions |
+{%- endif %}
+
+## Layer Responsibilities
+
+### API Routes (`api/routes/v1/`)
+- HTTP request/response handling
+- Input validation via Pydantic schemas
+- Authentication/authorization checks
+- Delegates to services for business logic
+
+### Services (`services/`)
+- Business logic and validation
+- Orchestrates repository calls
+- Raises domain exceptions (NotFoundError, etc.)
+- Transaction boundaries
+
+### Repositories (`repositories/`)
+- Database operations only
+- No business logic
+- Uses `db.flush()` not `commit()` (let dependency manage transactions)
+- Returns domain models
+
+## Key Files
+
+- Entry point: `app/main.py`
+- Configuration: `app/core/config.py`
+- Dependencies: `app/api/deps.py`
+{%- if cookiecutter.use_auth %}
+- Auth utilities: `app/core/security.py`
+{%- endif %}
+- Exception handlers: `app/api/exception_handlers.py`

fastapi_gen/template/{{cookiecutter.project_slug}}/docs/patterns.md

@@ -0,0 +1,161 @@
+# Code Patterns
+
+## Dependency Injection
+
+Use FastAPI's `Depends()` for injecting dependencies:
+
+```python
+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()
+```
+
+Available dependencies in `app/api/deps.py`:
+- `get_db` - Database session
+{%- if cookiecutter.use_auth %}
+- `get_current_user` - Authenticated user (raises 401 if not authenticated)
+- `get_current_user_optional` - User or None
+{%- endif %}
+{%- if cookiecutter.enable_redis %}
+- `get_redis` - Redis connection
+{%- endif %}
+
+## Service Layer Pattern
+
+Services contain business logic:
+
+```python
+class ItemService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+        self.repo = ItemRepository()
+
+    async def create(self, item_in: ItemCreate) -> Item:
+        # Business validation
+        if await self.repo.exists_by_name(self.db, item_in.name):
+            raise AlreadyExistsError(message="Item already exists")
+
+        # Create via repository
+        return await self.repo.create(self.db, **item_in.model_dump())
+
+    async def get_or_raise(self, id: UUID) -> Item:
+        item = await self.repo.get_by_id(self.db, id)
+        if not item:
+            raise NotFoundError(message="Item not found", details={"id": str(id)})
+        return item
+```
+
+## Repository Layer Pattern
+
+Repositories handle data access only:
+
+```python
+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()  # Not commit! Let dependency manage transaction
+        await db.refresh(item)
+        return item
+
+    async def get_multi(
+        self, db: AsyncSession, skip: int = 0, limit: int = 100
+    ) -> list[Item]:
+        result = await db.execute(
+            select(Item).offset(skip).limit(limit)
+        )
+        return list(result.scalars().all())
+```
+
+## Exception Handling
+
+Use domain exceptions in services:
+
+```python
+from app.core.exceptions import NotFoundError, AlreadyExistsError, ValidationError
+
+# In service
+if not item:
+    raise NotFoundError(
+        message="Item not found",
+        details={"id": str(id)}
+    )
+
+if await self.repo.exists_by_email(self.db, email):
+    raise AlreadyExistsError(
+        message="User with this email already exists"
+    )
+```
+
+Exception handlers convert to HTTP responses automatically.
+
+## Schema Patterns
+
+Separate schemas for different operations:
+
+```python
+# Base with shared fields
+class ItemBase(BaseModel):
+    name: str
+    description: str | None = None
+
+# For creation (input)
+class ItemCreate(ItemBase):
+    pass
+
+# For updates (all optional)
+class ItemUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+
+# For responses (with DB fields)
+class ItemResponse(ItemBase):
+    id: UUID
+    created_at: datetime
+    updated_at: datetime | None
+
+    model_config = ConfigDict(from_attributes=True)
+```
+{%- if cookiecutter.use_frontend %}
+
+## Frontend Patterns
+
+### Authentication (HTTP-only cookies)
+
+```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 %}

fastapi_gen/template/{{cookiecutter.project_slug}}/docs/testing.md

@@ -0,0 +1,120 @@
+# Testing Guide
+
+## Running Tests
+
+```bash
+cd backend
+
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=app --cov-report=term-missing
+
+# Run specific test file
+pytest tests/api/test_health.py -v
+
+# Run specific test
+pytest tests/api/test_health.py::test_health_check -v
+
+# Run only unit tests
+pytest tests/unit/
+
+# Run only integration tests
+pytest tests/integration/
+
+# Run with verbose output
+pytest -v
+
+# Stop on first failure
+pytest -x
+```
+
+## Test Structure
+
+```
+tests/
+├── conftest.py          # Shared fixtures
+├── api/                 # API endpoint tests
+│   ├── test_health.py
+│   └── test_auth.py
+├── unit/                # Unit tests (services, utils)
+│   └── test_services.py
+└── integration/         # Integration tests
+    └── test_db.py
+```
+
+## Key Fixtures (`conftest.py`)
+
+```python
+# Database session for tests
+@pytest.fixture
+async def db_session():
+    async with async_session() as session:
+        yield session
+        await session.rollback()
+
+# Test client
+@pytest.fixture
+def client():
+    return TestClient(app)
+
+# Authenticated client
+@pytest.fixture
+async def auth_client(client, test_user):
+    token = create_access_token(test_user.id)
+    client.headers["Authorization"] = f"Bearer {token}"
+    return client
+```
+
+## Writing Tests
+
+### API Endpoint Test
+```python
+def test_health_check(client):
+    response = client.get("/api/v1/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "healthy"
+```
+
+### Service Test
+```python
+async def test_create_item(db_session):
+    service = ItemService(db_session)
+    item = await service.create(ItemCreate(name="Test"))
+    assert item.name == "Test"
+```
+
+### Test with Authentication
+```python
+def test_protected_endpoint(auth_client):
+    response = auth_client.get("/api/v1/users/me")
+    assert response.status_code == 200
+```
+{%- if cookiecutter.use_frontend %}
+
+## Frontend Tests
+
+```bash
+cd frontend
+
+# Run unit tests
+bun test
+
+# Run with watch mode
+bun test --watch
+
+# Run E2E tests
+bun test:e2e
+
+# Run E2E in headed mode (see browser)
+bun test:e2e --headed
+```
+{%- endif %}
+
+## Test Database
+
+Tests use a separate test database or SQLite in-memory:
+- Configuration in `tests/conftest.py`
+- Database is reset between tests
+- Use fixtures for test data

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/.dockerignore

@@ -0,0 +1,40 @@
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Build outputs
+.next
+out
+build
+dist
+
+# Testing
+coverage
+.nyc_output
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Misc
+*.log
+.turbo

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/.env.example

@@ -0,0 +1,12 @@
+# Backend API URL (server-side only - not exposed to browser)
+BACKEND_URL=http://localhost:{{ cookiecutter.backend_port }}
+
+# WebSocket URL for real-time features
+BACKEND_WS_URL=ws://localhost:{{ cookiecutter.backend_port }}
+{%- if cookiecutter.enable_logfire %}
+
+# Logfire/OpenTelemetry (server-side instrumentation)
+# Get your write token from: https://logfire.pydantic.dev
+OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-api.pydantic.dev
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=your-logfire-write-token
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/.gitignore

@@ -0,0 +1,45 @@
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Testing
+coverage
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+.playwright/
+
+# Next.js
+.next/
+out/
+build
+
+# Misc
+.DS_Store
+*.pem
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# Bun
+bun.lockb

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/.prettierignore

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+
+# Build output
+.next/
+out/
+dist/
+
+# Cache
+.cache/
+
+# Misc
+*.log
+.DS_Store
+
+# Lock files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

fastapi_gen/template/{{cookiecutter.project_slug}}/frontend/Dockerfile

@@ -0,0 +1,44 @@
+FROM oven/bun:1 AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lockb* ./
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build the application
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN bun run build
+
+# Production image
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN useradd --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:bun /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:bun /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE {{ cookiecutter.frontend_port }}
+
+ENV PORT={{ cookiecutter.frontend_port }}
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["bun", "server.js"]