DeutschLernen/docs/features/infrastructure-setup.md

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
• Database Schema: Initial Database Schema
• Development: How to Run Vibe
• Application Plan: Application Plan

---

Feature created from application-plan.md