From 922ebf46ae01e090b45497730972daf6a699b5e2 Mon Sep 17 00:00:00 2001 From: ribardej Date: Wed, 15 Oct 2025 16:25:28 +0200 Subject: [PATCH] feat(docs): Catch up on report.md --- 7project/report.md | 302 +++++++++++++++++++++++++++++---------------- 1 file changed, 197 insertions(+), 105 deletions(-) diff --git a/7project/report.md b/7project/report.md index 1fc4231..ad53df0 100644 --- a/7project/report.md +++ b/7project/report.md @@ -7,126 +7,211 @@ ## Project Overview -**Project Name**: [Your project name] +**Project Name**: Personal Finance Tracker **Group Members**: -- Student number, Name, GitHub username -- Student number, Name, GitHub username -- Student number, Name, GitHub username +- Student number, Lukáš Trkan, lukastrkan +- 289258, Dejan Ribarovski, derib2613 **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 +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 -[Describe the overall system architecture. Consider including a diagram using mermaid or linking to an image] - ```mermaid -graph TD - A[Component A] --> B[Component B] - B --> C[Component C] +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 -- **Component 1**: [Description of what this component does] -- **Component 2**: [Description of what this component does] -- **Component 3**: [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. +- 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**: [e.g., Go, Node.js, Python] -- **Database**: [e.g., PostgreSQL, MongoDB, Redis] -- **Cloud Services**: [e.g., AWS EC2, Google Cloud Run, Azure Functions] -- **Container Orchestration**: [e.g., Docker, Kubernetes] -- **Other**: [List other significant technologies] +- 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: [e.g., Linux, macOS, Windows] -- Minimum RAM: [e.g., 8GB] -- Storage: [e.g., 10GB free space] +- 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 -- [Software 1] (version X.X or higher) -- [Software 2] (version X.X or higher) -- [etc.] +- 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) -### Dependencies +### Environment Variables (common) -```bash -# List key dependencies that need to be installed -# For example: -# Docker Engine 20.10+ -# Node.js 18+ -# Go 1.25+ -``` +- 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 -### 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 -git clone [your-repository-url] -cd [repository-name] +git clone https://github.com/dat515-2025/Group-8.git +cd 7project ``` -### 2. Install Dependencies - +### 2) Install dependencies +Backend ```bash -# Provide step-by-step commands -# For example: -# npm install -# go mod download +# In 7project/backend +python3.12 -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -r requirements.txt ``` - -### 3. Build the Application - +Frontend ```bash -# Provide exact build commands -# For example: -# make build -# docker build -t myapp . +# In 7project/frontend +npm install ``` -### 4. Configuration +### 3) Manual Local Run +Backend ```bash -# Any configuration steps needed -# Environment variables to set -# Configuration files to create +# 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 +```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 -### 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 -# Step-by-step commands for local deployment -# For example: -# docker-compose up -d -# kubectl apply -f manifests/ +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 ``` -### Cloud Deployment - +2) Deploy the app using Helm ```bash -# Commands for cloud deployment -# Include any cloud-specific setup +# 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: +```bash +kubectl -n myapp port-forward deploy/myapp-backend 8000:8000 +kubectl -n myapp port-forward deploy/myapp-frontend 5173:80 ``` ### Verification ```bash -# Commands to verify deployment worked -# How to check if services are running -# Example health check endpoints +# 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 @@ -156,19 +241,38 @@ cd [repository-name] ## Usage Examples -### Basic Usage +All endpoints are documented at OpenAPI: http://127.0.0.1:8000/docs + +### Auth: Register and Login (JWT) ```bash -# Examples of how to use the application -# Common commands or API calls -# Sample data or test scenarios +# 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 ``` -### Advanced Features +### Frontend -```bash -# Examples showcasing advanced functionality -``` +- 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. --- @@ -215,18 +319,18 @@ cd [repository-name] > 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 | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | -| [Design Document](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | -| [Backend API Development](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Hard | [Any notes] | -| [Database Setup & Models](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | -| [Frontend Development](https://github.com/dat515-2025/group-name) | [Name] | 🔄 In Progress | [X hours] | Medium | [Any notes] | -| [Docker Configuration](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | -| [Cloud Deployment](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Hard | [Any notes] | -| [Testing Implementation](https://github.com/dat515-2025/group-name) | [Name] | ⏳ Pending | [X hours] | Medium | [Any notes] | -| [Documentation](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Easy | [Any notes] | -| [Presentation Video](https://github.com/dat515-2025/group-name) | [Name] | ✅ Complete | [X hours] | Medium | [Any notes] | +| Task/Component | Assigned To | Status | Time Spent | Difficulty | 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-8/blob/main/6design/design.md) | Both | ✅ Complete | 2 Hours | Easy | [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-8/tree/main/7project/backend/app/models) | Lukas | ✅ Complete | [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-8/blob/main/7project/compose.yml) | Lukas | ✅ Complete | [X hours] | Easy | [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) | Dejan | ❌ Not Started | [X hours] | Medium | [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) | Both | ❌ Not Started | [X hours] | Medium | [Any notes] | **Legend**: ✅ Complete | 🔄 In Progress | ⏳ Pending | ❌ Not Started @@ -244,25 +348,16 @@ cd [repository-name] | [Date] | Documentation | [X.X] | Updated README and design doc | | **Total** | | **[XX.X]** | | -### [Team Member 2 Name] +### Dejan -| Date | Activity | Hours | Description | -| --------- | -------------------- | ---------- | ----------------------------------------- | -| [Date] | Frontend Development | [X.X] | Created user interface mockups | -| [Date] | Integration | [X.X] | Connected frontend to backend API | -| [Date] | Deployment | [X.X] | Docker configuration and cloud deployment | -| [Date] | Testing | [X.X] | End-to-end testing | -| **Total** | | **[XX.X]** | | +| 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** | | -### [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 @@ -292,11 +387,8 @@ cd [repository-name] [Personal reflection on growth, challenges, and learning] -#### [Team Member 3 Name] (if applicable) - -[Personal reflection on growth, challenges, and learning] --- **Report Completion Date**: [Date] -**Last Updated**: [Date] \ No newline at end of file +**Last Updated**: 15.10.2025 \ No newline at end of file