Project Details compliance

[DoPri]

Project Details Compliance

This issue tracks compliance with the project requirements outlined in .guidelines/Project Details.md.

Objective

• Complete DevOps-oriented software system designed and implemented
• Development, deployment, and operation treated as single engineering problem
• Web application with client, server, persistent storage, and GenAI component
• System is containerised and runnable locally
• Automated testing and deployment through GitHub Actions
• Deployable to Kubernetes
• Observable through Prometheus and Grafana
• Application domain is flexible but technical requirements are met

Development Workflow

• GitHub mono-repository used
• Feature branches for each change
• Pull requests mandatory before merge to main
• Peer review and approval by team members required
• CI pipeline runs automatically on every PR
• CD pipeline deploys automatically on merge to main

System Architecture

Client Side

• React application implemented
• Usable and responsive interface
• Interacts with server over REST APIs
• Uses generated TypeScript SDK from OpenAPI spec
• Uses SWR or React Query for data fetching with caching and retries
• Client implements actual document management functionality

Server Side

• Spring Boot (Java) implemented
• REST APIs exposed
• At least 3 microservices with distinct responsibilities
• Microservices communicate in a controlled, documented way
• Records (immutable) used for DTOs
• Each service is stateless where possible

Database

• PostgreSQL used (relational database)
• Runs via Docker in local dev
• Schema documented (users, documents, search schemas)
• One database per microservice (logical schema separation is fine)

GenAI Component

• Python with LangChain implemented
• Separate microservice, containerised independently
• Networked with server
• Real user-facing use case (summarisation, entity extraction, Q&A)
• Accessible through actual app workflow
• Supports cloud models (OpenAI API, TUM Logos gateway)
• Supports local models (Ollama)
• Full RAG setup with vector DB (Weaviate) - bonus feature

Environment and Deployment

Containerisation

• Client has its own Dockerfile
• Spring service has its own Dockerfile
• GenAI service has its own Dockerfile
• Database runs via Docker
• docker-compose.yml runs entire system end-to-end locally

Setup Simplicity

• Runnable in 3 or fewer commands (docker compose up)
• Sane defaults provided
• No complex manual ENV setup required
• New user can start without reverse-engineering

Kubernetes Deployment

• Deployable using Helm charts
• Works on course infrastructure (Rancher)
• Works on Azure (cloud option)
• Configuration externalised via env vars, Secrets, ConfigMaps
• No hardcoded tokens or environment-dependent values in manifests

CI/CD

Continuous Integration

• Build all services on every PR
• Run all automated tests on every PR
• Static analysis / linting on every PR
• OpenAPI spec linting on every PR
• Pipeline fails when system is broken

Continuous Deployment

• Auto-deploy to Kubernetes on merge to main
• Secrets and environment-specific variables used properly
• No hardcoded tokens
• Container images pushed to registry with semantic version tags and/or git SHA

Observability

• Prometheus used for metrics collection
• Request count tracked
• Latency tracked
• Error rate tracked
• Metrics cover server-side runtime behaviour
• Metrics cover GenAI component
• Grafana used for visualisation
• Dashboards reflect key system metrics
• Dashboards submitted as exported .json files
• At least one meaningful alert rule configured (4 alerts exist)

Testing

• Unit tests cover critical server logic
• Unit tests cover critical GenAI logic
• Client tests cover core workflows and interactions (Playwright E2E)
• E2E tests for system-wide flows
• All tests run automatically in CI pipeline
• Integration tests per microservice (with DB, external APIs)
• Pipeline acts as enforcement point for system stability

Engineering Artefacts

• High-level architecture description provided
• Subsystem decomposition documented
• Interfaces documented
• Subsystem Decomposition diagram (component_diagram.png)
• Use Case Diagram (use_case_diagram.png)
• Analysis Object Model (analysis_object_model.png)
• API documentation via OpenAPI/Swagger
• Swagger UI exposed

Deliverables

• Complete codebase for server, client, and GenAI services
• Dockerfiles and docker-compose.yml for local setup
• Helm charts for Kubernetes deployment with setup instructions
• Prometheus and Grafana config with exported dashboards and alert rules
• Testing suite with instructions to run
• README.md with setup guide, architecture, API docs, CI/CD and monitoring instructions
• Student responsibilities clearly documented

Common Pitfalls Avoided

• Reliability prioritized over feature count
• System treated as single pipeline (code → test → build → deploy → observe → improve)
• Reproducibility maintained (docker compose up works)
• Visible system behaviour (dashboards show meaningful metrics)
• Not treating project as checklist (meaningful implementation)
• Early integration (services integrated via docker-compose)
• Real CI/CD (not decorative)
• GenAI provides real user-facing value (not decoration)
• Documentation created as you go
• No long-running branches (feature branch workflow)
• No manual production deploys (everything through CI/CD)