youtube-summarizer/docs/stories/1.1.project-setup-infrastructure.md

Story 1.1: Project Setup and Infrastructure

Status

Draft

Story

As a developer
I want a fully configured project with all necessary dependencies and development tooling
so that the team can begin development with consistent environments and automated quality checks

Acceptance Criteria

1. FastAPI application structure created with proper package organization (api/, services/, models/, utils/)
2. Development environment configured with hot-reload, debugging, and environment variable management
3. Docker configuration enables single-command local development startup
4. Pre-commit hooks enforce code formatting (Black), linting (Ruff), and type checking (mypy)
5. GitHub Actions workflow runs tests and quality checks on every push
6. README includes clear setup instructions and architecture overview

Tasks / Subtasks

• Task 1: Backend Project Structure Setup (AC: 1)

  • Create FastAPI application entry point (backend/main.py)
  • Set up package structure: backend/{api,services,models,core,repositories}/
  • Initialize FastAPI app with CORS middleware and basic health endpoint
  • Create backend/requirements.txt with core dependencies

• Task 2: Frontend Project Structure Setup (AC: 1)

  • Initialize React TypeScript project in frontend/ directory
  • Install and configure shadcn/ui with Tailwind CSS
  • Set up project structure: frontend/src/{components,hooks,api,stores,types}/
  • Configure Vite build tool with TypeScript and React plugins

• Task 3: Development Environment Configuration (AC: 2)

  • Create .env.example file with all required environment variables
  • Set up FastAPI auto-reload and debugging configuration
  • Configure React development server with proxy to backend API
  • Create development scripts in package.json and document in README

• Task 4: Docker Configuration (AC: 3)

  • Create backend/Dockerfile with Python 3.11+ base image
  • Create frontend/Dockerfile with Node.js build and nginx serve
  • Create docker-compose.yml for full-stack development environment
  • Include health checks and volume mounts for hot-reload

• Task 5: Code Quality Tooling (AC: 4)

  • Configure pre-commit hooks with Black, Ruff, and mypy
  • Set up .pre-commit-config.yaml with Python and TypeScript checks
  • Add ESLint and Prettier configuration for frontend
  • Create pyproject.toml with tool configurations

• Task 6: CI/CD Pipeline (AC: 5)

  • Create GitHub Actions workflow for automated testing
  • Configure matrix testing for Python and Node.js versions
  • Set up code quality checks and test coverage reporting
  • Add workflow badges and status checks

• Task 7: Documentation (AC: 6)

  • Create comprehensive README.md with setup instructions
  • Document the self-hosted architecture overview
  • Add API documentation setup with FastAPI automatic docs
  • Include troubleshooting guide for common development issues

Dev Notes

Architecture Context

Based on the comprehensive architecture specifications, this story establishes the foundation for a self-hosted, hobby-scale YouTube Summarizer application using modern full-stack technologies.

Technology Stack

[Source: Architecture Specification - Technology Stack Overview]

Backend:

• FastAPI + Python 3.11+ for async API development
• SQLite for development (PostgreSQL for production later)
• Pydantic V2 for data validation and settings management
• SQLAlchemy 2.0 with async support for ORM

Frontend:

• React 18 + TypeScript for type-safe development
• shadcn/ui + Tailwind CSS for design system
• Zustand for state management
• React Query (@tanstack/react-query) for server state management

Development & Deployment:

• Docker Compose for self-hosted deployment
• Uvicorn ASGI server for backend
• Vite for frontend build tooling
• Pre-commit hooks for code quality

Project Structure Requirements

[Source: Architecture Specification - Project Structure]

youtube-summarizer/
├── frontend/                 # React TypeScript frontend
│   ├── src/
│   │   ├── components/      # UI components (shadcn/ui based)
│   │   ├── hooks/          # Custom React hooks  
│   │   ├── api/            # API client layer
│   │   ├── stores/         # Zustand stores
│   │   └── types/          # TypeScript definitions
│   ├── public/
│   └── package.json
├── backend/                  # FastAPI Python backend
│   ├── api/                # API endpoints
│   ├── services/           # Business logic
│   ├── models/             # Database models  
│   ├── repositories/       # Data access layer
│   ├── core/               # Core utilities
│   └── main.py
├── docker-compose.yml        # Self-hosted deployment
├── .env.example             # Environment template
└── README.md

Environment Variables Required

[Source: Architecture Specification - Environment Configuration]

# API Keys (at least one required)
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
DEEPSEEK_API_KEY=sk-your-deepseek-key

# Database
DATABASE_URL=sqlite:///./data/youtube_summarizer.db

# Security
SECRET_KEY=your-secret-key-here
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Application Settings
MAX_VIDEO_LENGTH_MINUTES=180
RATE_LIMIT_PER_MINUTE=30
CACHE_TTL_HOURS=24

Development Workflow Requirements

[Source: Architecture Specification - Self-Hosted Hobby Focus]

• Single Command Startup: docker-compose up should start the entire development environment
• Hot Reload: Both frontend and backend should support hot-reload for rapid development
• Type Safety: Complete TypeScript coverage with strict configuration
• Cost Optimization: Target ~$0.10/month with OpenAI GPT-4o-mini for hobby use
• Self-Hosted: No external cloud services required, runs entirely locally

Testing Standards

Testing Framework Requirements

[Source: Architecture Specification - Testing Strategy]

Backend Testing:

• Framework: pytest with asyncio support
• Location: backend/tests/
• Structure: tests/{unit,integration}/ separation
• Coverage: Minimum 80% code coverage requirement
• Patterns: Repository pattern testing, API endpoint testing, service layer mocking

Frontend Testing:

• Framework: Vitest + React Testing Library
• Location: frontend/src/test/ and co-located *.test.tsx files
• Setup: frontend/src/test/setup.ts for global test configuration
• Patterns: Component testing, custom hook testing, API client mocking

Test Configuration Files Required

• backend/pytest.ini - pytest configuration
• frontend/vitest.config.ts - Vitest configuration with path aliases
• frontend/src/test/setup.ts - Global test setup (jsdom, mocks)

Critical Implementation Notes

1. Self-Hosted Priority: All configuration must support local development and deployment without external cloud dependencies
2. Hobby Scale: Optimize for simplicity and learning over enterprise complexity
3. Modern Stack: Use latest stable versions of all frameworks and tools
4. Type Safety: Ensure complete TypeScript coverage across both frontend and backend APIs
5. Development Experience: Prioritize fast feedback loops and developer productivity

Change Log

Date	Version	Description	Author
2025-01-25	1.0	Initial story creation	Bob (Scrum Master)

Dev Agent Record

This section will be populated by the development agent during implementation

Agent Model Used

To be filled by dev agent

Debug Log References

To be filled by dev agent

Completion Notes List

To be filled by dev agent

File List

To be filled by dev agent

QA Results

Results from QA Agent review of the completed story implementation will be added here