team-drops

Repository for team DrOps.

Documentation

The project documentation is stored in the docs folder.

• Project Proposal
• System Structure
• Class Diagram
• Use Case Diagram
• Top-Level Architecture Diagram
• Microservice Best Practices
• Backend API Requirements

Product Backlog

The first product backlog is available in the GitHub Wiki:

• Product Backlog
• Product Backlog: User Stories

Project Structure

team-drops/
├── backend/
│   ├── user-service/               # Spring Boot — user registration, login, profiles (port 8081)
│   ├── learning-service/           # Spring Boot — learning plans, lessons, exercises (port 8082)
│   └── progress-feedback-service/  # Spring Boot — answers, feedback, progress (port 8083)
├── frontend/                       # React + TypeScript (Vite) — client UI, served by Nginx in Kubernetes
├── genai/                          # Python + FastAPI — LLM-powered generation and feedback (port 8084)
├── helm/team-drops/                # Helm chart for Rancher/Kubernetes deployment
├── shared/                         # Shared TypeScript types mirroring the backend domain model
├── docs/                           # Architecture diagrams and project proposal
├── .env.example                    # Environment variable reference
└── docker-compose.yml              # Local development setup

API Workflow

Main rule:

Update api/openapi.yaml first
→ generate code/types
→ implement business logic

API changes should be designed and reviewed before implementation.

Use versioned API paths from the beginning, for example:

/api/v1/users
/api/v1/learning-plans
/api/v1/progress

Export the central OpenAPI contract:

macOS/Linux:

bash api/scripts/export_openapi.sh

Windows PowerShell, using Git Bash explicitly:

& "C:\Program Files\Git\bin\bash.exe" api/scripts/export_openapi.sh

Then commit the updated OpenAPI files:

git add api/openapi.yaml api/services/*.yaml

CI fails if the committed OpenAPI files are out of sync with the code or generated specs.

Do not manually create duplicate DTOs or API request/response types.
Do not edit generated files manually.
If generated code is wrong, fix api/openapi.yaml and regenerate.

---

Backend

Backend services use OpenAPI Generator with the Spring generator.

The generator creates:

• API interfaces from OpenAPI paths
• DTO/model classes from OpenAPI schemas

The application code implements the generated interfaces and keeps business logic in the service layer.

Generate Java stubs:

openapi-generator-cli generate -i api/openapi.yaml -g spring -o backend/<service-name>/generated

If configured through Gradle:

./gradlew :<service-name>:openApiGenerate

Windows:

.\gradlew.bat :<service-name>:openApiGenerate

Project versions:

Spring Boot 4.x
Java 25 LTS

---

Frontend

Generate TypeScript API types from the OpenAPI spec:

npx openapi-typescript api/openapi.yaml -o frontend/src/api/types.ts

Do not hand-write request or response types.

For Kubernetes, the frontend image builds the Vite app into static files and serves them with Nginx.

Mock Server

For frontend development before backend implementation is ready:

npx prism mock api/openapi.yaml

---

Local Development

docker compose up --build

Kubernetes Deployment

The project is deployed to Rancher/Kubernetes with Helm. The chart lives in helm/team-drops and does not hardcode a namespace; pass the target namespace on the Helm command line.

Render and validate without changing the cluster:

helm lint ./helm/team-drops \
  -f helm/team-drops/values-rancher.yaml

helm template team-drops ./helm/team-drops \
  --namespace team-drops \
  -f helm/team-drops/values-rancher.yaml \
  | kubectl apply --dry-run=server -n team-drops -f -

Install or update the application:

helm upgrade --install team-drops ./helm/team-drops \
  --namespace team-drops \
  -f helm/team-drops/values-rancher.yaml

For a deploy with OpenAI, keep the API key out of Git and pass it at install time:

helm upgrade --install team-drops ./helm/team-drops \
  --namespace team-drops \
  -f helm/team-drops/values-rancher.yaml \
  --set genai.llmProvider=openai \
  --set genai.llmApiKey=<api-key>

For temporary tests with images built from a branch, add:

--set image.tag=kubernetes

After deployment, the ingress host exposes:

/                         frontend
/user-service/...          user-service
/learning-service/...      learning-service
/progress-service/...      progress-feedback-service
/api/v1/genai/...          genai-service

See helm/team-drops/README.md for validation, private image pull secrets, GenAI configuration, TLS notes, and troubleshooting commands.

CI/CD

The repository includes GitHub Actions workflows for continuous integration.

Workflow files:

.github/workflows/backend-ci.yml      # Builds all three Spring Boot services and their Docker images
.github/workflows/genai-ci.yml        # Tests and builds the GenAI service Docker image
.github/workflows/docker-publish.yml  # Builds all service images and publishes them to GHCR on main/tags/manual runs