76e8af4987
- Add comprehensive documentation in docs/ (architecture, features, roadmap) - Add german-app-frontend with Vite, TypeScript, ESLint configuration - Add AGENTS.md and .gitignore Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
273 lines
9.6 KiB
Markdown
273 lines
9.6 KiB
Markdown
# Feature: Infrastructure Setup
|
||
|
||
> **Status**: ⏳ Planned
|
||
> **Priority**: High
|
||
> **Complexity**: Medium
|
||
> **Estimate**: 10-14 hours
|
||
> **Assignee**: -
|
||
> **Created**: May 31, 2025
|
||
> **Target Completion**: -
|
||
> **Related Features**: All other features depend on this
|
||
|
||
---
|
||
|
||
## 📌 Overview
|
||
|
||
### Purpose
|
||
Establish the foundational infrastructure for the DeutschLernen application, including backend project, database, and core dependencies.
|
||
|
||
### User Story
|
||
As a developer, I want to have a working backend and database setup so that I can begin implementing application features.
|
||
|
||
### Acceptance Criteria
|
||
- [ ] .NET 9.0 backend project is created and builds successfully
|
||
- [ ] PostgreSQL database is configured and accessible
|
||
- [ ] Docker setup is ready for deployment
|
||
- [ ] CI/CD pipeline is configured
|
||
- [ ] Development environment is reproducible
|
||
|
||
---
|
||
|
||
## 📋 Requirements
|
||
|
||
### Functional Requirements
|
||
| ID | Requirement | Priority |
|
||
|----|-------------|----------|
|
||
| FR-001 | .NET 9.0 backend with ASP.NET Core Web API | High |
|
||
| FR-002 | PostgreSQL database with connection string configuration | High |
|
||
| FR-003 | Docker containers for backend and database | High |
|
||
| FR-004 | GitHub Actions CI/CD pipeline | Medium |
|
||
| FR-005 | Environment configuration (development, staging, production) | Medium |
|
||
|
||
### Non-Functional Requirements
|
||
- Performance: Backend should start in < 5 seconds
|
||
- Security: Database credentials stored securely (not in code)
|
||
- Compatibility: Works on Linux, Windows, and macOS
|
||
- Scalability: Infrastructure should support horizontal scaling
|
||
|
||
---
|
||
|
||
## 🏗️ Technical Design
|
||
|
||
### Components Involved
|
||
- **Backend**: ASP.NET Core Web API project
|
||
- **Database**: PostgreSQL 15+
|
||
- **Infrastructure**: Docker, Docker Compose
|
||
- **CI/CD**: GitHub Actions
|
||
|
||
### Architecture Diagram
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Infrastructure │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ Backend │ │ Database │ │ Frontend │ │
|
||
│ │ (.NET 9.0) │◄──►│ PostgreSQL │ │ (React) │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ ▲ ▲ ▲ │
|
||
│ │ │ │ │
|
||
│ ┌────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐ │
|
||
│ │ Docker │ │ Docker │ │ Docker │ │
|
||
│ │ Container│ │ Container │ │ Container │ │
|
||
│ └──────────┘ └───────────┘ └───────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Data Flow
|
||
1. Developer runs `docker-compose up`
|
||
2. PostgreSQL container starts with initialized database
|
||
3. Backend container starts and connects to database
|
||
4. Frontend container starts and connects to backend API
|
||
5. Application is accessible at `http://localhost:3000`
|
||
|
||
---
|
||
|
||
## 🚀 Implementation Plan
|
||
|
||
### Phase 1: Backend Project Setup (2-4 hours)
|
||
- [ ] Create GermanApp .NET 9.0 Web API project
|
||
- [ ] Configure appsettings.json with multiple environments
|
||
- [ ] Set up Health Checks endpoint
|
||
- [ ] Configure CORS for frontend
|
||
- [ ] Set up OpenAPI/Swagger documentation
|
||
- [ ] Configure logging (Serilog or built-in)
|
||
- [ ] Create base response models and error handling middleware
|
||
|
||
### Phase 2: Database Setup (1-2 hours)
|
||
- [ ] Design and create initial database schema
|
||
- [ ] Configure Entity Framework Core with PostgreSQL
|
||
- [ ] Set up database migrations
|
||
- [ ] Create seed data scripts
|
||
- [ ] Configure connection strings for different environments
|
||
|
||
### Phase 3: Docker Configuration (2-4 hours)
|
||
- [ ] Create Dockerfile for backend
|
||
- [ ] Create Dockerfile for frontend
|
||
- [ ] Create docker-compose.yml with all services
|
||
- [ ] Configure Docker volumes for persistent data
|
||
- [ ] Set up environment variables in Docker
|
||
- [ ] Test Docker build and run
|
||
|
||
### Phase 4: CI/CD Pipeline (2-4 hours)
|
||
- [ ] Create GitHub Actions workflow for backend
|
||
- [ ] Configure build, test, and deploy steps
|
||
- [ ] Set up environment secrets
|
||
- [ ] Configure branch protection rules
|
||
- [ ] Test CI/CD pipeline
|
||
|
||
### Milestones
|
||
| Milestone | Date | Status |
|
||
|-----------|------|--------|
|
||
| Backend Project Created | - | ⏳ |
|
||
| Database Configured | - | ⏳ |
|
||
| Docker Setup Complete | - | ⏳ |
|
||
| CI/CD Pipeline Working | - | ⏳ |
|
||
|
||
---
|
||
|
||
## ✅ Tasks
|
||
|
||
### Backend
|
||
- [ ] Initialize .NET 9.0 Web API project
|
||
- [ ] Configure Program.cs with proper middleware
|
||
- [ ] Set up appsettings.Development.json, appsettings.Staging.json, appsettings.Production.json
|
||
- [ ] Create HealthChecks endpoint
|
||
- [ ] Configure Swagger/OpenAPI
|
||
- [ ] Set up CORS policy
|
||
- [ ] Configure logging
|
||
- [ ] Create error handling middleware
|
||
- [ ] Create base response wrappers
|
||
|
||
### Database
|
||
- [ ] Install PostgreSQL locally for development
|
||
- [ ] Create initial database schema
|
||
- [ ] Configure EF Core DbContext
|
||
- [ ] Create first migration
|
||
- [ ] Apply migration to database
|
||
- [ ] Create seed data for initial testing
|
||
|
||
### Docker
|
||
- [ ] Create backend Dockerfile
|
||
- [ ] Create frontend Dockerfile
|
||
- [ ] Create docker-compose.yml
|
||
- [ ] Configure Docker volumes
|
||
- [ ] Set up Docker .env file
|
||
- [ ] Test Docker containers
|
||
|
||
### CI/CD
|
||
- [ ] Create .github/workflows/ directory
|
||
- [ ] Create backend CI workflow
|
||
- [ ] Create frontend CI workflow
|
||
- [ ] Configure deployment workflow
|
||
- [ ] Set up GitHub secrets
|
||
- [ ] Test workflows
|
||
|
||
---
|
||
|
||
## 🔗 Dependencies
|
||
|
||
### Feature Dependencies
|
||
- None - This is the foundational feature
|
||
|
||
### Technical Dependencies
|
||
- .NET 9.0 SDK
|
||
- PostgreSQL 15+
|
||
- Docker & Docker Compose
|
||
- GitHub account with repository access
|
||
|
||
### Blockers
|
||
- [ ] None identified
|
||
|
||
---
|
||
|
||
## ✅ Definition of Done
|
||
|
||
### General Criteria (All Features)
|
||
- [ ] All acceptance criteria met and verified
|
||
- [ ] All tasks in this document completed
|
||
- [ ] Code follows Clean Architecture principles
|
||
- [ ] Code reviewed and approved by at least 1 team member
|
||
- [ ] All tests passing (unit, integration)
|
||
- [ ] Documentation updated (README, AGENTS.md if applicable)
|
||
- [ ] Feature works in development environment
|
||
- [ ] Feature deployed to staging environment
|
||
- [ ] Performance meets defined targets
|
||
- [ ] Security review completed
|
||
- [ ] No critical bugs or blockers
|
||
|
||
### Infrastructure-Specific Criteria
|
||
- [ ] .NET 9.0 backend project builds successfully
|
||
- [ ] PostgreSQL database is accessible and configured
|
||
- [ ] Docker containers build and run without errors
|
||
- [ ] CI/CD pipeline runs successfully on push
|
||
- [ ] Development environment is reproducible by new team members
|
||
- [ ] Health checks pass for all services
|
||
- [ ] Database migrations can be applied cleanly
|
||
|
||
---
|
||
|
||
## 🧪 Testing Strategy
|
||
|
||
### Testing Approach
|
||
|
||
| Test Type | Coverage | Tools | Responsibility |
|
||
|-----------|----------|-------|----------------|
|
||
| Unit Tests | 80%+ code coverage | MsTest, Moq | Backend Dev |
|
||
| Integration Tests | All service interactions | MsTest, TestContainers | Backend Dev |
|
||
| API Tests | All endpoints | MsTest, HttpClient | Backend Dev |
|
||
| Frontend Unit Tests | Component logic | Vitest | Frontend Dev |
|
||
| Frontend Integration | Service integration | Vitest | Frontend Dev |
|
||
| E2E Tests | Critical user journeys | Playwright | QA/Dev |
|
||
| Manual Testing | Exploratory, edge cases | BrowserStack | QA |
|
||
|
||
### Infrastructure-Specific Tests
|
||
- [ ] Verify .NET 9.0 project structure
|
||
- [ ] Test database connection and queries
|
||
- [ ] Test Docker build process
|
||
- [ ] Test Docker Compose startup
|
||
- [ ] Test CI/CD pipeline execution
|
||
- [ ] Test health check endpoints
|
||
- [ ] Test database migration process
|
||
- [ ] Test backup and restore procedures
|
||
|
||
---
|
||
|
||
## 📝 Notes & Decisions
|
||
|
||
### Decisions Made
|
||
| Date | Decision | Rationale |
|
||
|------|----------|-----------|
|
||
| May 31, 2025 | Use PostgreSQL over SQLite | Better for production, supports more features, widely used |
|
||
| May 31, 2025 | Use Docker Compose | Simplified local development setup |
|
||
| May 31, 2025 | GitHub Actions for CI/CD | Native GitHub integration, free for public repos |
|
||
|
||
### Technical Notes
|
||
- Connection strings should use environment variables, not hardcoded values
|
||
- Docker volumes should be used for PostgreSQL data to persist between restarts
|
||
- Health checks should verify database connectivity
|
||
|
||
### Gotchas
|
||
- ⚠️ Docker on Windows may have volume mounting issues - use WSL2
|
||
- ⚠️ PostgreSQL container needs explicit volume for data persistence
|
||
- ⚠️ EF Core tools need to be installed for migrations
|
||
|
||
---
|
||
|
||
## 📊 Progress History
|
||
|
||
| Date | Status Change | Notes |
|
||
|------|---------------|-------|
|
||
| May 31, 2025 | Created | Initial plan based on application-plan.md |
|
||
|
||
---
|
||
|
||
## 📎 Related Files & Links
|
||
|
||
- Architecture: [Backend Structure](../architecture/backend-structure.md)
|
||
- Database Schema: [Initial Database Schema](../database/initial-database-schema.sql)
|
||
- Development: [How to Run Vibe](../development/how-to-run-vibe.md)
|
||
- Application Plan: [Application Plan](../architecture/application-plan.md)
|
||
|
||
---
|
||
|
||
*Feature created from application-plan.md*
|