uis-cloud-computing/7project/report.md

Personal finance tracker

Instructions: This template provides the structure for your project report. Replace the placeholder text with your actual content. Remove instructions that are not relevant for your project, but leave the headings along with a (NA) label.

Project Overview

Project Name: Personal Finance Tracker

Group Members:

• Student number, Lukáš Trkan, lukastrkan
• 289258, Dejan Ribarovski, derib2613, ribardej

Brief Description: Our application is a finance tracker, so a person can easily track his cash flow through multiple bank accounts. Person can label transactions with custom categories and later filter by them.

Architecture Overview

Our system is a full‑stack web application composed of a React frontend, a FastAPI backend, a PostgreSQL database, and asynchronous background workers powered by Celery with RabbitMQ. Redis is available for caching/kv and may be used by Celery as a result backend. The backend exposes REST endpoints for authentication (email/password and OAuth), users, categories, and transactions. A thin controller layer (FastAPI routers) lives under app/api. Infrastructure for Kubernetes is provided via OpenTofu (Terraform‑compatible) modules and the application is packaged via a Helm chart.

High-Level Architecture

flowchart LR
    proc_queue[Message Queue] --> proc_queue_worker[Worker Service]
    proc_queue_worker --> ext_mail[(Email Service)]
    proc_cron[Task planner] --> proc_queue
    proc_queue_worker --> ext_bank[(Bank API)]
    proc_queue_worker --> db
    client[Client/Frontend] <--> svc[Backend API]
    svc --> proc_queue
    svc <--> db[(Database)]
    svc <--> cache[(Cache)]

Components

• Frontend (frontend/): React + TypeScript app built with Vite. Talks to the backend via REST, handles login/registration, shows latest transactions, filtering, and allows adding transactions.
• Backend API (backend/app): FastAPI app with routers under app/api for auth, categories, and transactions. Uses FastAPI Users for auth (JWT + OAuth), SQLAlchemy ORM, and Pydantic v2 schemas.
• Worker service (backend/app/workers): Celery worker handling asynchronous tasks (e.g., sending verification emails, future background processing).
• Database (PostgreSQL): Persists users, categories, transactions; schema managed by Alembic migrations.
• Message Queue (RabbitMQ): Transports background jobs from the API to the worker.
• Cache/Result Store (Redis): Available for caching or Celery result backend.
• Infrastructure as Code (tofu/): OpenTofu modules provisioning cluster services (RabbitMQ, Redis, Argo CD, cert-manager, Cloudflare tunnel, etc.).
• Deployment Chart (charts/myapp-chart/): Helm chart to deploy the application to Kubernetes.

Technologies Used

• Backend: Python, FastAPI, FastAPI Users, SQLAlchemy, Pydantic, Alembic, Celery
• Frontend: React, TypeScript, Vite
• Database: PostgreSQL
• Messaging: RabbitMQ
• Cache: Redis
• Containerization/Orchestration: Docker, Docker Compose (dev), Kubernetes, Helm
• IaC/Platform: OpenTofu (Terraform), Argo CD, cert-manager, MetalLB, Cloudflare Tunnel, Prometheus

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows
• Minimum RAM: 4 GB (8 GB recommended for running backend, frontend, and database together)
• Storage: 2 GB free (Docker images may require additional space)

Required Software

• Docker Desktop or Docker Engine 24+
• Docker Compose v2+
• Node.js 20+ and npm 10+ (for local frontend dev/build)
• Python 3.12+ (for local backend dev outside Docker)
• PostgreSQL 15+ (optional if running DB outside Docker)
• Helm 3.12+ and kubectl 1.29+ (for Kubernetes deployment)
• OpenTofu 1.7+ (for infrastructure provisioning)

Environment Variables (common)

• Backend: SECRET, FRONTEND_URL, BACKEND_URL, DATABASE_URL, RABBITMQ_URL, REDIS_URL
• OAuth vars (Backend): MOJEID_CLIENT_ID/SECRET, BANKID_CLIENT_ID/SECRET (optional)
• Frontend: VITE_BACKEND_URL

Dependencies (key libraries)

I am not sure what is meant by "key libraries"

Backend: FastAPI, fastapi-users, SQLAlchemy, pydantic v2, Alembic, Celery
Frontend: React, TypeScript, Vite
Services: PostgreSQL, RabbitMQ, Redis

Build Instructions

You can run the project with Docker Compose (recommended for local development) or run services manually.

1) Clone the Repository

git clone https://github.com/dat515-2025/Group-8.git
cd 7project

2) Install dependencies

Backend

# In 7project/backend
python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Frontend

# In 7project/frontend
npm install

3) Manual Local Run

Backend

# From the 7project/ directory
docker compose up --build
# This starts: PostgreSQL, RabbitMQ/Redis (if defined)

# Set environment variables (or create .env file)
export SECRET=CHANGE_ME_SECRET
export BACKEND_URL=http://127.0.0.1:8000
export FRONTEND_URL=http://localhost:5173
export DATABASE_URL=postgresql+asyncpg://user:password@127.0.0.1:5432/app
export RABBITMQ_URL=amqp://guest:guest@127.0.0.1:5672/
export REDIS_URL=redis://127.0.0.1:6379/0

# Apply DB migrations (Alembic)
# From 7project/backend
alembic upgrade head

# Run API
uvicorn app.app:fastApi --reload --host 0.0.0.0 --port 8000

# Run Celery worker (optional, for emails/background tasks)
celery -A app.celery_app.celery_app worker -l info

Frontend

# Configure backend URL for dev
echo 'VITE_BACKEND_URL=http://127.0.0.1:8000' > .env
npm run dev
# Open http://localhost:5173

• Backend default: http://127.0.0.1:8000 (OpenAPI at /docs)
• Frontend default: http://localhost:5173

If needed, adjust compose services/ports in compose.yml.

Deployment Instructions

Local (Docker Compose)

Described in the previous section (Manual Local Run)

Kubernetes (via OpenTofu + Helm)

1. Provision platform services (RabbitMQ/Redis/ingress/tunnel/etc.) with OpenTofu

cd tofu
# copy and edit variables
cp terraform.tfvars.example terraform.tfvars
# authenticate to your cluster/cloud as needed, then:
tofu init
tofu plan
tofu apply

2. Deploy the app using Helm

# Set the namespace
kubectl create namespace myapp || true

# Install/upgrade the chart with required values
helm upgrade --install myapp charts/myapp-chart \
  -n myapp \
  -f charts/myapp-chart/values.yaml \
  --set image.backend.repository=myorg/myapp-backend \
  --set image.backend.tag=latest \
  --set env.BACKEND_URL="https://myapp.example.com" \
  --set env.FRONTEND_URL="https://myapp.example.com" \
  --set env.SECRET="CHANGE_ME_SECRET"

Adjust values to your registry and domain. The chart’s NOTES.txt includes additional examples.

3. Expose and access

• If using Cloudflare Tunnel or an ingress, configure DNS accordingly (see tofu/modules/cloudflare and deployment/tunnel.yaml).
• For quick testing without ingress:

kubectl -n myapp port-forward deploy/myapp-backend 8000:8000
kubectl -n myapp port-forward deploy/myapp-frontend 5173:80

Verification

# Check pods
kubectl -n myapp get pods

# Backend health
curl -i http://127.0.0.1:8000/
# OpenAPI
open http://127.0.0.1:8000/docs

# Frontend (if port-forwarded)
open http://localhost:5173

Testing Instructions

Unit Tests

# Commands to run unit tests
# For example:
# go test ./...
# npm test

Integration Tests

# Commands to run integration tests
# Any setup required for integration tests

End-to-End Tests

# Commands to run e2e tests
# How to set up test environment

Usage Examples

All endpoints are documented at OpenAPI: http://127.0.0.1:8000/docs

Auth: Register and Login (JWT)

# Register
curl -X POST http://127.0.0.1:8000/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "StrongPassw0rd",
    "first_name": "Jane",
    "last_name": "Doe"
  }'

# Login (JWT)
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/auth/jwt/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=user@example.com&password=StrongPassw0rd' | jq -r .access_token)

echo $TOKEN

# Call a protected route
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/authenticated-route

Frontend

• Start with: npm run dev in 7project/frontend
• Ensure VITE_BACKEND_URL is set to the backend URL (e.g., http://127.0.0.1:8000)
• Open http://localhost:5173
• Login, view latest transactions, filter, and add new transactions from the UI.

---

Presentation Video

YouTube Link: [Insert your YouTube link here]

Duration: [X minutes Y seconds]

Video Includes:

• Project overview and architecture
• Live demonstration of key features
• Code walkthrough
• Build and deployment showcase

Troubleshooting

Common Issues

Issue 1: [Common problem]

Symptoms: [What the user sees] Solution: [Step-by-step fix]

Issue 2: [Another common problem]

Symptoms: [What the user sees] Solution: [Step-by-step fix]

Debug Commands

# Useful commands for debugging
# Log viewing commands
# Service status checks

---

Self-Assessment Table

Be honest and detailed in your assessments. This information is used for individual grading. Link to the specific commit on GitHub for each contribution.

Task/Component	Assigned To	Status	Time Spent	Difficulty	Notes
Project Setup & Repository	Lukas	✅ Complete	[X hours]	Medium	[Any notes]
Design Document	Both	✅ Complete	2 Hours	Easy	[Any notes]
Backend API Development	Dejan	✅ Complete	10 hours	Medium	[Any notes]
Database Setup & Models	Lukas	✅ Complete	[X hours]	Medium	[Any notes]
Frontend Development	Dejan	🔄 In Progress	7 hours so far	Medium	[Any notes]
Docker Configuration	Lukas	✅ Complete	[X hours]	Easy	[Any notes]
Cloud Deployment	Lukas	✅ Complete	[X hours]	Hard	[Any notes]
Testing Implementation	Dejan	❌ Not Started	[X hours]	Medium	[Any notes]
Documentation	Both	❌ Not Started	[X hours]	Easy	[Any notes]
Presentation Video	Both	❌ Not Started	[X hours]	Medium	[Any notes]

Legend: ✅ Complete | 🔄 In Progress | ⏳ Pending | ❌ Not Started

Hour Sheet

Link to the specific commit on GitHub for each contribution.

[Team Member 1 Name]

Date	Activity	Hours	Description
[Date]	Initial Setup	[X.X]	Repository setup, project structure
[Date]	Backend Development	[X.X]	Implemented user authentication
[Date]	Testing	[X.X]	Unit tests for API endpoints
[Date]	Documentation	[X.X]	Updated README and design doc
Total		[XX.X]

Dejan

Date	Activity	Hours	Description
25.9.	Design	1.5	6design
9-11.10.	Backend APIs	10	Implemented Backend APIs
13-15.10.	Frontend Development	6.5	Created user interface mockups
Continually	Documantation	3	Documenting the dev process
Total		21

Group Total: [XXX.X] hours

---

Final Reflection

What We Learned

[Reflect on the key technical and collaboration skills learned during this project]

Challenges Faced

[Describe the main challenges and how you overcame them]

If We Did This Again

[What would you do differently? What worked well that you'd keep?]

Individual Growth

[Team Member 1 Name]

[Personal reflection on growth, challenges, and learning]

[Team Member 2 Name]

[Personal reflection on growth, challenges, and learning]

---

Report Completion Date: [Date] Last Updated: 15.10.2025