red64-cli 0.1.0 → 0.3.0

package/framework/stacks/python/structure.md

@@ -1,78 +1,265 @@
 # Project Structure
 
-## Project: {{projectName}}
-
 ## Organization Philosophy
 
-Package-based organization with clear module boundaries. Each package is self-contained with its own models, services, and routes.
+Modern Python packaging with `src` layout. Clear separation between application code, tests, and configuration. Domain-driven modules as complexity grows.
+
+---
 
 ## Directory Patterns
 
-### Application Package
-**Location**: `/src/{{projectName}}/` or `/app/`
-**Purpose**: Main application code
-**Example**: __init__.py, main.py
-
-### API Routes
-**Location**: `/src/api/` or `/app/routers/`
-**Purpose**: HTTP endpoint definitions
-**Example**: users.py, auth.py
-
-### Models
-**Location**: `/src/models/`
-**Purpose**: Pydantic models and SQLAlchemy models
-**Example**: user.py, schemas.py
-
-### Services
-**Location**: `/src/services/`
-**Purpose**: Business logic
-**Example**: user_service.py, email_service.py
-
-### Repositories
-**Location**: `/src/repositories/`
-**Purpose**: Data access layer
-**Example**: user_repository.py
-
-### Core
-**Location**: `/src/core/`
-**Purpose**: Shared utilities, config, dependencies
-**Example**: config.py, dependencies.py, security.py
-
-### Tests
-**Location**: `/tests/`
-**Purpose**: Test files mirroring src structure
-**Example**: test_users.py, conftest.py
-
-## Naming Conventions
-
-- **Files**: snake_case.py (user_service.py, auth_router.py)
-- **Classes**: PascalCase (UserService, UserSchema)
-- **Functions**: snake_case (get_user, validate_token)
-- **Constants**: UPPER_SNAKE_CASE
-- **Packages**: snake_case (my_package/)
+### Root Layout
+
+```
+project-root/
+  pyproject.toml          # Project metadata, dependencies, tool config
+  uv.lock                 # Locked dependencies
+  .python-version         # Python version pin
+  alembic.ini             # Migration config
+  docker-compose.yml      # Local services
+  Dockerfile              # Production image
+  .env.example            # Environment template (never commit .env)
+  src/
+    app/                  # Application package
+  tests/                  # Test suite
+  migrations/             # Alembic migrations
+  scripts/                # Utility scripts
+```
+
+### Application Core (`src/app/`)
+
+**Purpose**: All application code in a single installable package
+**Pattern**: Domain modules with clear boundaries
+
+```
+src/app/
+  __init__.py
+  main.py                 # Application entry point, ASGI app factory
+  config.py               # Settings via pydantic-settings
+  dependencies.py         # Dependency injection setup
+  models/                 # SQLAlchemy/Django models
+    __init__.py
+    user.py
+    content.py
+    base.py               # Base model with common fields
+  schemas/                # Pydantic request/response models
+    __init__.py
+    user.py
+    content.py
+  services/               # Business logic layer
+    __init__.py
+    user_service.py
+    content_service.py
+  api/                    # Route handlers (FastAPI routers)
+    __init__.py
+    v1/
+      __init__.py
+      users.py
+      content.py
+  repositories/           # Data access layer
+    __init__.py
+    user_repo.py
+    content_repo.py
+  middleware/              # ASGI middleware
+    __init__.py
+    auth.py
+    logging.py
+  tasks/                  # Background tasks (Celery/arq)
+    __init__.py
+    content_tasks.py
+  utils/                  # Shared utilities
+    __init__.py
+    hashing.py
+    pagination.py
+```
+
+### Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Packages | snake_case | `user_service/`, `api/` |
+| Modules | snake_case | `user_service.py`, `auth_middleware.py` |
+| Models | PascalCase, singular | `User`, `ContentVersion` |
+| Schemas | PascalCase + purpose | `CreateUserRequest`, `UserResponse` |
+| Services | PascalCase + Service | `UserService`, `ContentService` |
+| Repositories | PascalCase + Repo/Repository | `UserRepo` |
+| Tables | plural, snake_case | `users`, `content_versions` |
+
+---
+
+## Package Configuration (`pyproject.toml`)
+
+### Minimal Structure
+
+```toml
+[project]
+name = "my-app"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "sqlalchemy[asyncio]>=2.0",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "asyncpg>=0.29",
+    "redis>=5.0",
+    "alembic>=1.13",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "factory-boy>=3.3",
+    "faker>=30.0",
+    "httpx>=0.27",
+    "ruff>=0.8",
+    "mypy>=1.13",
+    "pre-commit>=4.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/app"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "SIM", "TCH", "RUF"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+```
+
+---
 
 ## Import Organization
 
+### Pattern: Absolute Imports
+
 ```python
-# 1. Standard library
+# Standard library
+from collections.abc import AsyncIterator
 from datetime import datetime
-from typing import Optional
 
-# 2. Third-party packages
-from fastapi import FastAPI, Depends
-from pydantic import BaseModel
+# Third-party
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
 
-# 3. Local application imports
-from app.core.config import settings
+# Application (absolute from package root)
+from app.models.user import User
+from app.schemas.user import CreateUserRequest, UserResponse
 from app.services.user_service import UserService
+from app.dependencies import get_db, get_current_user
+```
+
+Ruff enforces import sorting (`I` rules). No manual ordering needed.
+
+---
+
+## Configuration Pattern
+
+### Pydantic Settings
+
+```python
+# src/app/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+    )
+
+    # Database
+    database_url: str = "postgresql+asyncpg://localhost:5432/myapp"
+
+    # Redis
+    redis_url: str = "redis://localhost:6379/0"
+
+    # Auth
+    secret_key: str
+    access_token_expire_minutes: int = 30
+
+    # External services
+    openai_api_key: str = ""
+
+settings = Settings()
+```
+
+---
+
+## Dependency Injection Pattern (FastAPI)
+
+```python
+# src/app/dependencies.py
+from collections.abc import AsyncIterator
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+async def get_db() -> AsyncIterator[AsyncSession]:
+    async with async_session_factory() as session:
+        yield session
+
+async def get_user_service(
+    db: AsyncSession = Depends(get_db),
+) -> UserService:
+    return UserService(repo=UserRepo(db))
+```
+
+---
+
+## Migration Organization (`migrations/`)
+
 ```
+migrations/
+  env.py                  # Alembic environment config
+  versions/
+    001_create_users.py
+    002_create_content.py
+    003_add_user_roles.py
+```
+
+**Naming**: Prefix with sequential number for readability alongside Alembic's revision IDs.
+
+---
 
-## Code Organization Principles
+## Test Organization (`tests/`)
 
-- **Explicit Imports**: No wildcard imports
-- **Dependency Injection**: Use FastAPI Depends or manual DI
-- **Single Responsibility**: Each module has one purpose
-- **Clean Architecture**: Dependencies flow inward
+```
+tests/
+  conftest.py             # Shared fixtures (db, client, factories)
+  unit/
+    services/
+      test_user_service.py
+    utils/
+      test_hashing.py
+  integration/
+    api/
+      test_users.py
+      test_content.py
+    repositories/
+      test_user_repo.py
+  factories/
+    user_factory.py
+    content_factory.py
+```
+
+**Pattern**: Mirror `src/app/` structure in `tests/`. Separate unit and integration tests.
 
 ---
-_Document patterns, not file trees. New files following patterns shouldn't require updates_
+
+_Document patterns, not file trees. New files following patterns should not require updates._

package/framework/stacks/python/tech.md

@@ -1,64 +1,121 @@
 # Technology Stack
 
-## Project: {{projectName}}
-
 ## Architecture
 
-Modular architecture with clear separation between API layer, business logic, and data access. Uses dependency injection for testability.
+Modern Python application with async-first design. FastAPI or Django as web framework, PostgreSQL for persistence, Redis for caching and task queues, Docker for deployment.
+
+---
 
 ## Core Technologies
 
-- **Language**: Python 3.11+
-- **Framework**: FastAPI / Django / Flask
-- **Package Manager**: uv / pip / poetry
+- **Language**: Python 3.12+
+- **Package Manager**: uv (fast, Rust-based)
+- **Web Framework**: FastAPI (API-first) or Django (full-stack)
+- **Database**: PostgreSQL with asyncpg
+- **ORM**: SQLAlchemy 2.0 (async) or Django ORM
+- **Cache/Queue**: Redis with redis-py
+
+---
 
 ## Key Libraries
 
-- **Validation**: Pydantic
-- **Database**: SQLAlchemy / asyncpg / Motor
-- **HTTP Client**: httpx / aiohttp
-- **Testing**: pytest / pytest-asyncio
+### Web & API
+- **FastAPI**: High-performance async API framework
+- **Uvicorn**: ASGI server (production: with gunicorn)
+- **Pydantic v2**: Request/response validation, settings
+- **python-multipart**: Form/file upload handling
 
-## Development Standards
+### Database & Storage
+- **SQLAlchemy 2.0**: Async ORM with type-safe queries
+- **Alembic**: Database migrations
+- **asyncpg**: Async PostgreSQL driver
+- **boto3**: AWS S3 for file storage (when needed)
+
+### Background Tasks
+- **Celery**: Distributed task queue (with Redis broker)
+- **arq**: Lightweight async task queue alternative
+- **APScheduler**: Scheduled/cron jobs
 
-### Type Safety
-- Type hints on all function signatures
-- Pydantic models for data validation
-- mypy for static type checking
-- No `Any` types except when interfacing with untyped libraries
+### Deployment
+- **Docker**: Containerized deployment
+- **Docker Compose**: Multi-service local development
+- **Gunicorn + Uvicorn**: Production ASGI serving
+
+---
+
+## Development Standards
 
 ### Code Quality
-- Ruff for linting and formatting
-- Black for code formatting
-- isort for import sorting
+- **Ruff**: Linting and formatting (replaces black, isort, flake8)
+- **mypy**: Static type checking (strict mode)
+- **pre-commit**: Git hooks for automated checks
+
+### Security
+- **bandit**: Security vulnerability scanner
+- **safety**: Dependency vulnerability scanning
+- **python-dotenv**: Environment-based configuration (never commit `.env`)
 
 ### Testing
-- pytest for all tests
-- pytest-cov for coverage reporting
-- Minimum 80% coverage for business logic
-- Fixtures for common test setup
+- **pytest**: Test framework with fixtures and parametrize
+- **pytest-asyncio**: Async test support
+- **pytest-cov**: Coverage reporting
+- **factory-boy + faker**: Test data generation
+- **httpx**: Async HTTP client for integration tests
+
+---
 
 ## Development Environment
 
 ### Required Tools
-- Python 3.11+
-- uv or pip
-- Docker (for databases)
+- Python 3.12+ (see `.python-version`)
+- uv (package manager)
+- PostgreSQL 16+
+- Redis 7+
+- Docker & Docker Compose
 
 ### Common Commands
 ```bash
-# Dev: uv run uvicorn main:app --reload
-# Test: uv run pytest
-# Lint: uv run ruff check .
-# Format: uv run ruff format .
+# Environment setup
+uv sync                          # Install dependencies
+uv run alembic upgrade head      # Run migrations
+
+# Dev server
+uv run uvicorn app.main:app --reload          # FastAPI
+uv run python manage.py runserver             # Django
+
+# Tests
+uv run pytest                    # All tests
+uv run pytest tests/unit/        # Unit tests only
+uv run pytest --cov=src          # With coverage
+
+# Code quality
+uv run ruff check .              # Lint
+uv run ruff format .             # Format
+uv run mypy src/                 # Type check
+
+# Database
+uv run alembic revision --autogenerate -m "description"  # New migration
+uv run alembic upgrade head                              # Apply migrations
+uv run alembic downgrade -1                              # Rollback one
+
+# Docker
+docker compose up -d             # Start services
+docker compose logs -f app       # Follow app logs
 ```
 
+---
+
 ## Key Technical Decisions
 
-- **Async**: Use async/await for I/O operations
-- **Dependency Injection**: Use FastAPI's Depends for DI
-- **Environment**: Use pydantic-settings for configuration
-- **Logging**: Structured logging with structlog
+| Decision | Rationale |
+|----------|-----------|
+| **uv over pip/poetry** | 10-100x faster installs, built-in venv, lockfile support |
+| **Ruff over black+isort+flake8** | Single tool, Rust-based speed, drop-in replacement |
+| **Pydantic v2 over attrs/marshmallow** | Native FastAPI integration, Rust core, JSON Schema |
+| **SQLAlchemy 2.0 async** | Type-safe queries, async support, mature ecosystem |
+| **PostgreSQL over SQLite** | Production-grade, JSONB, full-text search, concurrency |
+| **Redis for cache + queue** | Versatile: caching, Celery broker, pub/sub, rate limiting |
 
 ---
-_Document standards and patterns, not every dependency_
+
+_Document standards and patterns, not every dependency. See `python.md` for detailed Python conventions._