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]

```bash
# 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*