fastapi-fullstack 0.2.2__tar.gz → 0.2.4__tar.gz

{fastapi_fullstack-0.2.2 → fastapi_fullstack-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullstack
-Version: 0.2.2
+Version: 0.2.4
 Summary: Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability.
 Project-URL: Homepage, https://github.com/vstorm-co/full-stack-ai-agent-template
 Project-URL: Documentation, https://github.com/vstorm-co/full-stack-ai-agent-template#readme
@@ -27,11 +27,11 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
-Requires-Dist: mypy>=1.13.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: ty>=0.0.29; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'

{fastapi_fullstack-0.2.2 → fastapi_fullstack-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-fullstack"
-version = "0.2.2"
+version = "0.2.4"
 description = "Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -58,7 +58,7 @@ dev = [
     "pytest>=8.0.0",
     "pytest-cov>=4.0.0",
     "ruff>=0.8.0",
-    "mypy>=1.13.0",
+    "ty>=0.0.29",
     "pre-commit>=3.0.0",
 ]
 docs = [
@@ -134,25 +134,16 @@ indent-style = "space"
 skip-magic-trailing-comma = false
 line-ending = "auto"
 
-[tool.mypy]
-python_version = "3.11"
-strict = true
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-disallow_incomplete_defs = true
-check_untyped_defs = true
-ignore_missing_imports = true
-# Exclude Jinja2 template files
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.src]
+# Exclude Jinja2 template files and integration tests with dynamic imports
 exclude = [
     "template/",
+    "tests/",
 ]
 
-[[tool.mypy.overrides]]
-module = "fastapi_gen.config"
-# Pydantic's @computed_field on top of @property is valid but mypy doesn't like it
-disable_error_code = ["prop-decorator"]
-
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
@@ -177,6 +168,6 @@ exclude_lines = [
 
 [dependency-groups]
 dev = [
-    "mypy>=1.19.1",
+    "ty>=0.0.29",
     "pytest-cov>=7.0.0",
 ]

{fastapi_fullstack-0.2.2 → fastapi_fullstack-0.2.4}/template/hooks/post_gen_project.py

@@ -263,6 +263,8 @@ if not use_frontend:
     if os.path.exists(frontend_dir):
         shutil.rmtree(frontend_dir)
         print("Removed frontend/ directory (frontend not enabled)")
+    # Remove frontend-specific Claude rule
+    remove_file(os.path.join(os.getcwd(), ".claude", "rules", "frontend.md"))
 
 
 # Remove .env files if generate_env is false

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/commands/add-endpoint.md

@@ -0,0 +1,40 @@
+---
+description: Scaffold a new API endpoint with full layering
+---
+
+Create a new API endpoint: $ARGUMENTS
+
+Follow the project's layered architecture. Create files in this order:
+
+1. **Schema** (`backend/app/schemas/<entity>.py`):
+   - Inherit `BaseSchema` (and `TimestampSchema` for Read)
+   - Create `*Create`, `*Update`, `*Read`, `*List` models
+   - Use `Field()` with constraints, `EmailStr` where applicable
+
+2. **DB Model** (`backend/app/db/models/<entity>.py`):
+   - Inherit `Base, TimestampMixin`
+   - Use `Mapped[type]` + `mapped_column()`
+   - Add `__repr__`, relationships with `cascade="all, delete-orphan"`
+
+3. **Repository** (`backend/app/repositories/<entity>_repo.py`):
+   - Stateless async functions: `get_by_id`, `get_multi`, `create`, `update`, `delete`
+   - Use `db.flush()` + `db.refresh()`, keyword-only args after `db`
+
+4. **Service** (`backend/app/services/<entity>.py`):
+   - Class with `__init__(self, db: AsyncSession)`
+   - Raise `NotFoundError`, `AlreadyExistsError` as appropriate
+
+5. **DI** (`backend/app/api/deps.py`):
+   - Add factory function and `Annotated` alias: `EntitySvc = Annotated[EntityService, Depends(get_entity_service)]`
+
+6. **Route** (`backend/app/api/routes/v1/<entity>.py`):
+   - CRUD: GET list, GET by id, POST (201), PATCH, DELETE (204)
+   - Use DI aliases, `response_model`, `-> Any` return type
+
+7. **Register** router in `backend/app/api/routes/v1/__init__.py`
+
+8. **Migration**: `cd backend && uv run alembic revision --autogenerate -m "Add <entity> table"`
+
+9. **Test** (`backend/tests/`): mirror source structure
+
+10. Lint: `cd backend && uv run ruff check . --fix && uv run ruff format .`

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/commands/fix-issue.md

@@ -0,0 +1,16 @@
+---
+description: Investigate and fix an issue
+---
+
+Fix the issue: $ARGUMENTS
+
+1. **Understand** — search the codebase for relevant code, read the files, understand current behavior
+2. **Reproduce** — if possible, identify a test case or request that triggers the issue
+3. **Root cause** — trace through Routes → Services → Repositories to find where the bug originates
+4. **Fix** — implement the fix following project conventions:
+   - Domain exceptions in services (not HTTP errors)
+   - `db.flush()` in repositories (not `commit`)
+   - Type hints on all changed signatures
+5. **Test** — run `cd backend && uv run pytest` to verify no regressions
+6. **Lint** — run `cd backend && uv run ruff check . --fix && uv run ruff format .`
+7. **Summary** — explain what was changed and why

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/commands/review.md

@@ -0,0 +1,31 @@
+---
+description: Review code changes against project conventions
+---
+
+Review all staged and unstaged changes in the current branch.
+
+For each changed file, verify:
+
+**Architecture:**
+- Routes only call services, never repositories
+- Services raise domain exceptions (NotFoundError, AlreadyExistsError, etc.), not HTTP exceptions
+- Repositories use `db.flush()` + `db.refresh()`, never `db.commit()`
+- DI uses Annotated aliases from `deps.py` (CurrentUser, *Svc), not raw `Depends()` in signatures
+
+**Schemas & Types:**
+- Separate Create/Update/Read/List Pydantic models
+- Type hints on all function signatures (params + return)
+- Modern syntax: `str | None` not `Optional[str]`
+- Route return type is `-> Any`
+
+**Code Quality:**
+- No debug code (print, commented-out code, TODO without issue reference)
+- No security issues (SQL injection, exposed secrets, missing auth)
+- Consistent naming (snake_case functions, PascalCase classes)
+- Imports ordered: stdlib → third-party → local
+
+**Validation:**
+1. Run `cd backend && uv run ruff check .`
+2. Run `cd backend && uv run pytest` (if test files changed)
+
+Provide findings with specific file:line references and suggest fixes.

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/api-conventions.md

@@ -0,0 +1,90 @@
+---
+description: API design, REST conventions, auth, pagination, response format
+globs: ["backend/app/api/**/*.py"]
+---
+
+# API Conventions
+
+## Route Structure
+
+- All routes under `/api/v1/` prefix
+- One file per domain entity in `api/routes/v1/`
+- Use `APIRouter()` with tags
+
+## HTTP Methods & Status Codes
+
+```python
+# GET — read
+@router.get("/{id}", response_model=EntityRead)
+
+# GET list — paginated
+@router.get("", response_model=EntityList)
+
+# POST — create (201)
+@router.post("", response_model=EntityRead, status_code=status.HTTP_201_CREATED)
+
+# PATCH — partial update
+@router.patch("/{id}", response_model=EntityRead)
+
+# DELETE — no content (204)
+@router.delete("/{id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+```
+
+## Pagination
+
+```python
+@router.get("", response_model=ConversationList)
+async def list_items(
+    service: ConversationSvc,
+    user: CurrentUser,
+    skip: int = Query(0, ge=0, description="Items to skip"),
+    limit: int = Query(50, ge=1, le=100, description="Max items to return"),
+) -> Any:
+    items, total = await service.list(user_id=user.id, skip=skip, limit=limit)
+    return ConversationList(items=items, total=total)
+```
+
+## Authentication
+
+- `CurrentUser` — JWT Bearer token (any authenticated user)
+- `CurrentAdmin` — JWT + admin role check via `RoleChecker`
+- `ValidAPIKey` — API key from header (service-to-service)
+
+```python
+# Protected endpoint
+async def get_profile(user: CurrentUser) -> Any: ...
+
+# Admin-only endpoint
+async def delete_user(user: CurrentAdmin) -> Any: ...
+
+# API key endpoint
+async def webhook_callback(api_key: ValidAPIKey) -> Any: ...
+```
+
+## Response Format
+
+All route handlers return `-> Any`. The `response_model` parameter handles serialization.
+
+Error responses follow this JSON structure:
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found",
+    "details": {"user_id": "..."}
+  }
+}
+```
+
+## File Upload
+
+```python
+@router.post("/me/avatar", response_model=UserRead)
+async def upload_avatar(
+    file: UploadFile = File(...),
+    user: CurrentUser,
+    service: UserSvc,
+) -> Any:
+    data = await file.read()
+    return await service.update_avatar(user.id, data, file.filename or "avatar.jpg")
+```

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/architecture.md

@@ -0,0 +1,109 @@
+---
+description: Layered architecture patterns — Routes, Services, Repositories, DI
+globs: ["backend/app/**/*.py"]
+---
+
+# Architecture
+
+## Layered Architecture: Routes → Services → Repositories
+
+Routes NEVER import or call repositories directly. Always go through a service.
+
+## Repositories (`app/repositories/`)
+
+Pure data access — stateless functions (not classes):
+
+```python
+async def get_by_id(db: AsyncSession, entity_id: UUID) -> Entity | None:
+    result = await db.execute(select(Entity).where(Entity.id == entity_id))
+    return result.scalar_one_or_none()
+
+async def create(db: AsyncSession, *, field1: str, field2: str) -> Entity:
+    entity = Entity(field1=field1, field2=field2)
+    db.add(entity)
+    await db.flush()
+    await db.refresh(entity)
+    return entity
+
+async def update(db: AsyncSession, *, db_entity: Entity, update_data: dict[str, Any]) -> Entity:
+    for field, value in update_data.items():
+        setattr(db_entity, field, value)
+    await db.flush()
+    await db.refresh(db_entity)
+    return db_entity
+
+async def delete(db: AsyncSession, entity_id: UUID) -> Entity | None:
+    entity = await get_by_id(db, entity_id)
+    if entity:
+        await db.delete(entity)
+        await db.flush()
+    return entity
+```
+
+Rules:
+- ALWAYS `db.flush()` + `db.refresh()`, NEVER `db.commit()` — session auto-commits in `get_db_session`
+- Use keyword-only args after `db`: `create(db, *, email: str, name: str)`
+- Return the entity (or None for get/delete), never return IDs or dicts
+- Functions are async for PostgreSQL/MongoDB, sync for SQLite
+
+## Services (`app/services/`)
+
+Business logic — class-based with DB session:
+
+```python
+class UserService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def get_by_id(self, user_id: UUID) -> User:
+        user = await user_repo.get_by_id(self.db, user_id)
+        if not user:
+            raise NotFoundError(message="User not found", details={"user_id": user_id})
+        return user
+
+    async def create(self, data: UserCreate) -> User:
+        existing = await user_repo.get_by_email(self.db, data.email)
+        if existing:
+            raise AlreadyExistsError(message="Email already registered", details={"email": data.email})
+        hashed_password = get_password_hash(data.password)
+        return await user_repo.create(self.db, email=data.email, hashed_password=hashed_password)
+```
+
+Rules:
+- Raise domain exceptions, NEVER return error codes or None for "not found"
+- Services call repo functions, never build raw queries
+- One service per domain entity
+
+## Dependency Injection (`app/api/deps.py`)
+
+Use `Annotated` type aliases — never raw `Depends()` in route signatures:
+
+```python
+DBSession = Annotated[AsyncSession, Depends(get_db_session)]
+UserSvc = Annotated[UserService, Depends(get_user_service)]
+CurrentUser = Annotated[User, Depends(get_current_user)]
+CurrentAdmin = Annotated[User, Depends(RoleChecker(UserRole.ADMIN))]
+```
+
+Service factories take `DBSession` and return service instances:
+
+```python
+def get_user_service(db: DBSession) -> UserService:
+    return UserService(db)
+```
+
+## Routes (`app/api/routes/v1/`)
+
+HTTP layer only — validate, delegate, return:
+
+```python
+@router.get("/{user_id}", response_model=UserRead)
+async def get_user(user_id: UUID, service: UserSvc, user: CurrentUser) -> Any:
+    return await service.get_by_id(user_id)
+```
+
+Rules:
+- Return type is always `-> Any` (response_model handles serialization)
+- Use `status_code=status.HTTP_201_CREATED` for POST, `HTTP_204_NO_CONTENT` for DELETE
+- DELETE endpoints: `response_model=None`
+- Pagination: `skip: int = Query(0, ge=0)`, `limit: int = Query(50, ge=1, le=100)`

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/code-style.md

@@ -0,0 +1,67 @@
+---
+description: Code style, formatting, naming, imports, and type hints
+globs: ["backend/**/*.py", "*.py"]
+---
+
+# Code Style
+
+## Formatting
+
+- Use `ruff` for linting and formatting: `ruff check . --fix && ruff format .`
+- Line length: 120 characters
+
+## Type Hints
+
+- Type hints on ALL function signatures — parameters and return types
+- Use modern syntax: `str | None` not `Optional[str]`, `list[User]` not `List[User]`
+- Use `Annotated[Type, Depends(...)]` for DI (defined as aliases in `deps.py`)
+- Use `dict[str, Any]` for generic dicts
+- Use `Literal["value1", "value2"]` for string enums in schemas
+- Use `TYPE_CHECKING` block for circular import resolution:
+  ```python
+  from typing import TYPE_CHECKING
+  if TYPE_CHECKING:
+      from app.db.models.session import Session
+  ```
+
+## Naming
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Files | snake_case | `user_repo.py`, `conversation_service.py` |
+| Classes | PascalCase | `UserService`, `ConversationRead` |
+| Functions/variables | snake_case | `get_by_id`, `user_service` |
+| Constants | UPPER_CASE | `DEFAULT_SYSTEM_PROMPT` |
+| Private | _leading_underscore | `_create_agent` |
+| DB tables | snake_case plural | `users`, `conversations` |
+| API URLs | kebab-case | `/api/v1/conversations` |
+
+## Imports — strictly ordered, separated by blank lines
+
+```python
+# 1. Standard library
+import logging
+from collections.abc import AsyncGenerator
+from datetime import UTC, datetime
+from typing import Annotated, Any
+from uuid import UUID
+
+# 2. Third-party
+from fastapi import APIRouter, Depends, Query, status
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. Local application
+from app.api.deps import CurrentUser, UserSvc
+from app.core.exceptions import NotFoundError
+from app.schemas.user import UserCreate, UserRead
+```
+
+## Other Conventions
+
+- `datetime.now(UTC)` not `datetime.utcnow()`
+- `secrets.compare_digest()` for constant-time comparisons
+- `__repr__` on all DB models
+- Async for PostgreSQL/MongoDB I/O, sync for SQLite
+- Keyword-only args in repo functions after `db` parameter

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/exceptions-security.md

@@ -0,0 +1,54 @@
+---
+description: Exception handling patterns and security conventions
+globs: ["backend/app/core/**/*.py", "backend/app/services/**/*.py"]
+---
+
+# Exceptions & Security
+
+## Domain Exceptions (`app/core/exceptions.py`)
+
+All extend `AppException`. Always pass `message` and `details`:
+
+```python
+raise NotFoundError(message="User not found", details={"user_id": str(user_id)})
+raise AlreadyExistsError(message="Email already registered", details={"email": email})
+raise AuthenticationError(message="Invalid or expired token")
+raise AuthorizationError(message="Role 'admin' required for this action")
+```
+
+Exception handlers in `api/exception_handlers.py` automatically:
+- Map to HTTP status codes
+- Log with structured context (path, method, error code)
+- Return consistent JSON error format
+- Add `WWW-Authenticate: Bearer` header on 401
+
+## Security Patterns
+
+JWT auth (`core/security.py`):
+- `create_access_token(subject)` / `create_refresh_token(subject)` — encode with `jwt.encode()`
+- `verify_token(token)` → `dict | None` — decode with `jwt.decode()`
+- Token payload: `{"exp": ..., "sub": user_id, "type": "access"|"refresh"}`
+
+Password hashing:
+- `get_password_hash(password)` — bcrypt
+- `verify_password(plain, hashed)` — bcrypt `checkpw`
+- NEVER store plain passwords
+
+API keys:
+- `secrets.compare_digest()` for constant-time comparison
+- `APIKeyHeader(name=settings.API_KEY_HEADER, auto_error=False)`
+
+## Role-Based Access Control
+
+```python
+class RoleChecker:
+    def __init__(self, required_role: UserRole) -> None:
+        self.required_role = required_role
+
+    async def __call__(self, user: Annotated[User, Depends(get_current_user)]) -> User:
+        if not user.has_role(self.required_role):
+            raise AuthorizationError(message=f"Role '{self.required_role.value}' required")
+        return user
+
+CurrentAdmin = Annotated[User, Depends(RoleChecker(UserRole.ADMIN))]
+```

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/frontend.md

@@ -0,0 +1,27 @@
+---
+description: Frontend conventions for Next.js
+globs: ["frontend/**/*.ts", "frontend/**/*.tsx", "frontend/**/*.css"]
+---
+
+# Frontend Conventions
+
+## Stack
+
+- Next.js 15 with App Router
+- TypeScript strict mode
+- Tailwind CSS for styling
+- i18n support built-in
+
+## Structure
+
+- Pages in `frontend/src/app/` following Next.js App Router conventions
+- Reusable components in `frontend/src/components/`
+- API client functions in `frontend/src/lib/`
+- Types in `frontend/src/types/`
+
+## Conventions
+
+- Use `"use client"` directive only when component needs client-side interactivity
+- Prefer Server Components by default
+- Use `fetch` with proper error handling for API calls
+- Keep components small and focused — extract when a component exceeds ~100 lines

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/.claude/rules/schemas-models.md

@@ -0,0 +1,90 @@
+---
+description: Pydantic schema patterns and SQLAlchemy model conventions
+globs: ["backend/app/schemas/**/*.py", "backend/app/db/models/**/*.py", "backend/app/db/base.py"]
+---
+
+# Schemas & Models
+
+## Pydantic Schemas (`app/schemas/`)
+
+Base schema with shared config:
+
+```python
+class BaseSchema(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+```
+
+Separate models per operation:
+
+```python
+class UserCreate(BaseSchema):
+    email: EmailStr = Field(max_length=255)
+    password: str = Field(min_length=8, max_length=128)
+    full_name: str | None = Field(default=None, max_length=255)
+
+class UserUpdate(BaseSchema):
+    email: EmailStr | None = Field(default=None, max_length=255)
+    password: str | None = Field(default=None, min_length=8, max_length=128)
+    full_name: str | None = Field(default=None, max_length=255)
+    is_active: bool | None = None
+
+class UserRead(BaseSchema, TimestampSchema):
+    id: UUID
+    email: EmailStr
+    full_name: str | None = None
+    role: UserRole = UserRole.USER
+    avatar_url: str | None = None
+
+class UserList(BaseSchema):
+    items: list[UserRead]
+    total: int
+```
+
+Rules:
+- `*Create` — required fields for creation, with `Field()` constraints
+- `*Update` — all fields optional (`type | None = None`)
+- `*Read` — includes `id` and timestamps, inherits `TimestampSchema`
+- `*List` — `items` list + `total` count
+- Use `@field_validator` for complex deserialization (e.g., JSON string → dict)
+
+## SQLAlchemy Models (`app/db/models/`)
+
+```python
+class User(Base, TimestampMixin):
+    __tablename__ = "users"
+
+    id: Mapped[UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True, nullable=False)
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    conversations: Mapped[list["Conversation"]] = relationship(
+        "Conversation", back_populates="user", cascade="all, delete-orphan"
+    )
+
+    def __repr__(self) -> str:
+        return f"<User(id={self.id}, email={self.email})>"
+```
+
+Rules:
+- Always inherit `Base` and `TimestampMixin` (provides `created_at`, `updated_at`)
+- Use `Mapped[type]` with `mapped_column()` for all columns
+- ForeignKey with `ondelete="CASCADE"` for parent references
+- Always define `__repr__`
+- Naming convention in `Base.metadata`: `{table}_{col}_key`, `{table}_{col}_fkey`, etc.
+
+## TimestampMixin
+
+```python
+class TimestampMixin:
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), onupdate=func.now(), nullable=True
+    )
+```