# 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**:

- 289229, Lukáš Trkan, lukastrkan
- 289258, Dejan Ribarovski, derib2613, ribardej

**Brief Description**: (něco spíš jako abstract, introuction, story behind)
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

```mermaid
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

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

### 2) Install dependencies
Backend
```bash
# In 7project/backend
python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
Frontend
```bash
# In 7project/frontend
npm install
```

### 3) Manual Local Run

Backend
```bash
# 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 (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
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
```bash
# 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
# 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

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

### Integration Tests

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

### End-to-End Tests

```bash
# 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)

```bash
# 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

```bash
# 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](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

## Hour Sheet

> Link to the specific commit on GitHub for each contribution.

### [Lukáš]

| Date           | Activity            | Hours      | Description                                        |
|----------------|---------------------|------------|----------------------------------------------------|
| 4.10 to 10.10  | Initial Setup       | 40         | Repository setup, project structure, cluster setup |
| 14.10 to 16.10 | Backend Development | 12         | Implemented user authentication - oauth            |
| 8.10 to 12.10  | CI/CD               | 10         | Created database schema and models                 |
| [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