lukas/uis-cloud-computing
1
0
Fork 0
mirror of https://github.com/dat515-2025/Group-8.git synced 2026-03-22 15:12:08 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat(docs): Catch up on report.md

Browse Source
This commit is contained in:
ribardej
2025-10-15 16:25:28 +02:00
parent e200c73b47
commit 922ebf46ae
1 changed files with 197 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
7project/report.md
View File

@@ -7,126 +7,211 @@
## Project Overview ## Project Overview
**Project Name**: [Your project name] **Project Name**: Personal Finance Tracker
**Group Members**: **Group Members**:
- Student number, Name, GitHub username - Student number, Lukáš Trkan, lukastrkan
- Student number, Name, GitHub username - 289258, Dejan Ribarovski, derib2613
- Student number, Name, GitHub username
**Brief Description**: **Brief Description**:
[2-3 sentences describing what your application does and its main purpose] 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 ## 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 ### High-Level Architecture
[Describe the overall system architecture. Consider including a diagram using mermaid or linking to an image]
```mermaid ```mermaid
graph TD flowchart LR
A[Component A] --> B[Component B] proc_queue[Message Queue] --> proc_queue_worker[Worker Service]
B --> C[Component C] 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 ### Components
- **Component 1**: [Description of what this component does] - 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.
- **Component 2**: [Description of what this component does] - 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.
- **Component 3**: [Description of what this component does] - 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 ### Technologies Used
- **Backend**: [e.g., Go, Node.js, Python] - Backend: Python, FastAPI, FastAPI Users, SQLAlchemy, Pydantic, Alembic, Celery
- **Database**: [e.g., PostgreSQL, MongoDB, Redis] - Frontend: React, TypeScript, Vite
- **Cloud Services**: [e.g., AWS EC2, Google Cloud Run, Azure Functions] - Database: PostgreSQL
- **Container Orchestration**: [e.g., Docker, Kubernetes] - Messaging: RabbitMQ
- **Other**: [List other significant technologies] - Cache: Redis
- Containerization/Orchestration: Docker, Docker Compose (dev), Kubernetes, Helm
- IaC/Platform: OpenTofu (Terraform), Argo CD, cert-manager, MetalLB, Cloudflare Tunnel, Prometheus
## Prerequisites ## Prerequisites
### System Requirements ### System Requirements
- Operating System: [e.g., Linux, macOS, Windows] - Operating System: Linux, macOS, or Windows
- Minimum RAM: [e.g., 8GB] - Minimum RAM: 4 GB (8 GB recommended for running backend, frontend, and database together)
- Storage: [e.g., 10GB free space] - Storage: 2 GB free (Docker images may require additional space)
### Required Software ### Required Software
- [Software 1] (version X.X or higher) - Docker Desktop or Docker Engine 24+
- [Software 2] (version X.X or higher) - Docker Compose v2+
- [etc.] - 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)
### Dependencies ### Environment Variables (common)
```bash - Backend: SECRET, FRONTEND_URL, BACKEND_URL, DATABASE_URL, RABBITMQ_URL, REDIS_URL
# List key dependencies that need to be installed - OAuth vars (Backend): MOJEID_CLIENT_ID/SECRET, BANKID_CLIENT_ID/SECRET (optional)
# For example: - Frontend: VITE_BACKEND_URL
# Docker Engine 20.10+
# Node.js 18+ ### Dependencies (key libraries)
# Go 1.25+ 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 ## Build Instructions
### 1. Clone the Repository You can run the project with Docker Compose (recommended for local development) or run services manually.
### 1) Clone the Repository
```bash ```bash
git clone [your-repository-url] git clone https://github.com/dat515-2025/Group-8.git
cd [repository-name] cd 7project
``` ```
### 2. Install Dependencies ### 2) Install dependencies
Backend
```bash ```bash
# Provide step-by-step commands # In 7project/backend
# For example: python3.12 -m venv .venv
# npm install source .venv/bin/activate # Windows: .venv\Scripts\activate
# go mod download pip install -r requirements.txt
``` ```
Frontend
### 3. Build the Application
```bash ```bash
# Provide exact build commands # In 7project/frontend
# For example: npm install
# make build
# docker build -t myapp .
``` ```
### 4. Configuration ### 3) Manual Local Run
Backend
```bash ```bash
# Any configuration steps needed # From the 7project/ directory
# Environment variables to set docker compose up --build
# Configuration files to create # 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
```bash
# 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 ## Deployment Instructions
### Local Deployment ### 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
```bash ```bash
# Step-by-step commands for local deployment cd tofu
# For example: # copy and edit variables
# docker-compose up -d cp terraform.tfvars.example terraform.tfvars
# kubectl apply -f manifests/ # authenticate to your cluster/cloud as needed, then:
tofu init
tofu plan
tofu apply
``` ```
### Cloud Deployment 2) Deploy the app using Helm
```bash ```bash
# Commands for cloud deployment # Set the namespace
# Include any cloud-specific setup 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:
```bash
kubectl -n myapp port-forward deploy/myapp-backend 8000:8000
kubectl -n myapp port-forward deploy/myapp-frontend 5173:80
``` ```
### Verification ### Verification
```bash ```bash
# Commands to verify deployment worked # Check pods
# How to check if services are running kubectl -n myapp get pods
# Example health check endpoints
# 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 ## Testing Instructions
@@ -156,19 +241,38 @@ cd [repository-name]
## Usage Examples ## Usage Examples
### Basic Usage All endpoints are documented at OpenAPI: http://127.0.0.1:8000/docs
### Auth: Register and Login (JWT)
```bash ```bash
# Examples of how to use the application # Register
# Common commands or API calls curl -X POST http://127.0.0.1:8000/auth/register \
# Sample data or test scenarios -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
``` ```
### Advanced Features ### Frontend
```bash - Start with: npm run dev in 7project/frontend
# Examples showcasing advanced functionality - 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.
--- ---
@@ -216,17 +320,17 @@ cd [repository-name]
> Link to the specific commit on GitHub for each contribution. > Link to the specific commit on GitHub for each contribution.
| Task/Component | Assigned To | Status | Time Spent | Difficulty | Notes | | Task/Component | Assigned To | Status | Time Spent | Difficulty | Notes |
| ------------------------------------------------------------------- | ----------- | ------------- | ---------- | ---------- | ----------- | |-----------------------------------------------------------------------|-------------| ------------- |----------------|------------| ----------- |
| Project Setup & Repository | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | | [Project Setup & Repository](https://github.com/dat515-2025/Group-8#) | Lukas | ✅ Complete | [X hours] | Medium | [Any notes] |
| [Design Document](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | | [Design Document](https://github.com/dat515-2025/Group-8/blob/main/6design/design.md) | Both | ✅ Complete | 2 Hours | Easy | [Any notes] |
| [Backend API Development](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Hard | [Any notes] | | [Backend API Development](https://github.com/dat515-2025/Group-8/tree/main/7project/backend/app/api) | Dejan | ✅ Complete | 10 hours | Medium | [Any notes] |
| [Database Setup & Models](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | | [Database Setup & Models](https://github.com/dat515-2025/Group-8/tree/main/7project/backend/app/models) | Lukas | ✅ Complete | [X hours] | Medium | [Any notes] |
| [Frontend Development](https://github.com/dat515-2025/group-name) | [Name] | 🔄 In Progress | [X hours] | Medium | [Any notes] | | [Frontend Development](https://github.com/dat515-2025/Group-8/tree/main/7project/frontend) | Dejan | 🔄 In Progress | 7 hours so far | Medium | [Any notes] |
| [Docker Configuration](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | | [Docker Configuration](https://github.com/dat515-2025/Group-8/blob/main/7project/compose.yml) | Lukas | ✅ Complete | [X hours] | Easy | [Any notes] |
| [Cloud Deployment](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Hard | [Any notes] | | [Cloud Deployment](https://github.com/dat515-2025/Group-8/blob/main/7project/deployment/app-demo-deployment.yaml) | Lukas | ✅ Complete | [X hours] | Hard | [Any notes] |
| [Testing Implementation](https://github.com/dat515-2025/group-name) | [Name] | ⏳ Pending | [X hours] | Medium | [Any notes] | | [Testing Implementation](https://github.com/dat515-2025/group-name) | Dejan | ❌ Not Started | [X hours] | Medium | [Any notes] |
| [Documentation](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | | [Documentation](https://github.com/dat515-2025/group-name) | Both | ❌ Not Started | [X hours] | Easy | [Any notes] |
| [Presentation Video](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | | [Presentation Video](https://github.com/dat515-2025/group-name) | Both | ❌ Not Started | [X hours] | Medium | [Any notes] |
**Legend**: ✅ Complete | 🔄 In Progress | ⏳ Pending | ❌ Not Started **Legend**: ✅ Complete | 🔄 In Progress | ⏳ Pending | ❌ Not Started
@@ -244,25 +348,16 @@ cd [repository-name]
| [Date] | Documentation | [X.X] | Updated README and design doc | | [Date] | Documentation | [X.X] | Updated README and design doc |
| **Total** | | **[XX.X]** | | | **Total** | | **[XX.X]** | |
### [Team Member 2 Name] ### Dejan
| Date | Activity | Hours | Description | | Date | Activity | Hours | Description |
| --------- | -------------------- | ---------- | ----------------------------------------- | |-------------|----------------------|--------|--------------------------------|
| [Date] | Frontend Development | [X.X] | Created user interface mockups | | 25.9. | Design | 1.5 | 6design |
| [Date] | Integration | [X.X] | Connected frontend to backend API | | 9-11.10. | Backend APIs | 10 | Implemented Backend APIs |
| [Date] | Deployment | [X.X] | Docker configuration and cloud deployment | | 13-15.10. | Frontend Development | 6.5 | Created user interface mockups |
| [Date] | Testing | [X.X] | End-to-end testing | | Continually | Documantation | 3 | Documenting the dev process |
| **Total** | | **[XX.X]** | | | **Total** | | **21** | |
### [Team Member 3 Name] (if applicable)
| Date | Activity | Hours | Description |
| --------- | ------------------------ | ---------- | -------------------------------- |
| [Date] | Database Design | [X.X] | Schema design and implementation |
| [Date] | Cloud Configuration | [X.X] | AWS/GCP setup and configuration |
| [Date] | Performance Optimization | [X.X] | Caching and query optimization |
| [Date] | Monitoring | [X.X] | Logging and monitoring setup |
| **Total** | | **[XX.X]** | |
### Group Total: [XXX.X] hours ### Group Total: [XXX.X] hours
@@ -292,11 +387,8 @@ cd [repository-name]
[Personal reflection on growth, challenges, and learning] [Personal reflection on growth, challenges, and learning]
#### [Team Member 3 Name] (if applicable)
[Personal reflection on growth, challenges, and learning]
--- ---
**Report Completion Date**: [Date] **Report Completion Date**: [Date]
**Last Updated**: [Date] **Last Updated**: 15.10.2025