uis-cloud-computing/6design/design.md

# Design Document

> Keep this document brief (2–4 pages), clear, and up-to-date throughout the project.
> You may use Mermaid diagrams for architecture visuals.

| Field          | Value (fill in)                        |
| -------------- |----------------------------------------|
| Project Name   | Personal Finance Tracker               |
| Team Members   | Lukáš Trkan, Dejan Ribarovski          |
| Repository URL | https://github.com/dat515-2025/Group-8 |
| Version        | v0.1 (update as you iterate)           |
| Last Updated   | YYYY-MM-DD                             |

## How to use this template

- Replace all placeholders with your project-specific content.
- Keep explanations concise; link to code or docs when helpful.
- Update this document as the design evolves to match the final implementation.

---

## 1. Overview

Briefly describe the application and its purpose.

- Problem statement: What problem are you solving?
  - Keeping track of all personal finances across multiple bank accounts, cash is not easy. We want to simplify it.
- Target users / personas: Who benefits from this?
    - We aim to help people to keep better track of their finance flows, so people can plan bigger expenses or find ways to save money.
- Primary objectives: 3–5 bullet points.
  - Pass th
- Non-goals: What is explicitly out of scope?
- Key features: Short bullet list of core functionality.

## 2. Architecture

High-level architecture, main components, interactions, and data flow. Include a system diagram.

### 2.1 System diagram

```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/UI] --> api[API Gateway / Web Server]
    api --> svc[Web API]
    svc --> proc_queue
    svc --> db[(Database)]
    svc --> cache[(Cache)]
```

- Components and responsibilities: What does each box do?
- Data flow: How does data move between components?
- State management: Where is state stored (DB, cache, object store)?
- External dependencies: APIs, third-party services, webhooks.

### 2.2 Data model (if applicable)

- Core entities and relationships (ER sketch or brief description).
- Example records or schemas (link to files or include concise snippets).
- Users, Transactions, Transaction_Categories, User_settings

```mermaid
erDiagram
    USERS {
        int user_id PK
        string name
        string email
    }

    TRANSACTIONS {
        int transaction_id PK
        int user_id FK
        int category_id FK
        decimal amount
        date transaction_date
    }

    TRANSACTION_CATEGORIES {
        int category_id PK
        string name
        string type
        string color
    }

    USER_SETTINGS {
        int setting_id PK
        int user_id FK
        string setting_key
        string setting_value
    }

    USERS ||--o{ TRANSACTIONS : "makes"
    USERS ||--o{ USER_SETTINGS : "has"
    TRANSACTION_CATEGORIES ||--o{ TRANSACTIONS : "categorizes"
```

### 2.3 APIs (REST/gRPC/GraphQL)

- Swagger

## 3. Technologies

List the cloud services, libraries, and tools you will use and why.

| Technology / Service | Role / Where Used | Why chosen (brief) | Alternatives considered |
| -------------------- | ----------------- | ------------------ | ----------------------- |
| Python | Back-End | Simplest for both of us | Java, C#, PHP |
| React | Front-End | Most popular, we dont have exp with FE | Vue, plain JS |
| REST | BE<->FE API | Simplest | GraphQL |
| MariaDB | Database | Prior experience | PostgreSQL, CockroachDB |
| Redis | Cache | Prior experience | Valkey, Memcached |
| RabbitMQ | Message queue | Prior experience | MQTT, Redis |
| Python Fast API | API Framework | Simplicity | Flask, Django |
| Open Tofu | Cluster deployment | Prior experience | Terraform |
| Talos Cluster | Deployment | Why not | Docker swarn, RKE | 

Notes:

- Languages & frameworks (e.g., Go, Node, Python; Gin, Fiber, Echo).
- Cloud provider and managed services (compute, DB, storage, messaging).
- CI/CD, IaC, containerization.

## 4. Deployment

Describe the deployment strategy and infrastructure requirements.

- Environments: prod, local dev
- Runtime platform: Kubernetes, serverless - cloudflare pages
- Infrastructure diagram (optional):

```mermaid
flowchart TB
    subgraph "Cloudflare"
        pages[React App<br/>Cloudflare Pages]
    end
    
    subgraph "Kubernetes Cluster"
        subgraph "Ingress"
            ingress[Ingress Controller]
        end
        
        subgraph "Services"
            api[API Gateway /<br/>Web Server]
            svc[Web API Service]
            worker[Worker Service]
            planner[Task Planner]
        end
        
        subgraph "Infrastructure"
            queue[Message Queue]
            db[(Database)]
            cache[(Cache)]
        end
    end
    
    user((User)) --> pages
    pages -.-> ingress
    ingress --> api
    api --> svc
    svc --> queue
    svc --> db
    svc --> cache
    
    queue --> worker
    planner --> queue
    
    worker --> db

```

- Configuration & secrets: Env vars, secret manager, .env files (never commit secrets).
- Build & release: How artifacts are built; link to CI/CD if used.
- Deployment steps: Summarize here; full, reproducible steps must be in report.md.
- Scaling strategy: Horizontal/vertical scaling, autoscaling triggers.

---

## Optional Sections

Include the sections below as applicable to your project.

### Security

- Authn/Authz model; data protection; TLS/HTTPS; secrets handling; dependency scanning.

### Scalability

- Expected load; performance targets; bottlenecks; caching; rate limits.

### Monitoring & Logging

- Health checks; logs; metrics (e.g., Prometheus); dashboards; alerting.

### Disaster Recovery

- Backups; restore procedures; RPO/RTO targets; failure scenarios.

### Cost Analysis

- Main cost drivers; pricing model; cost-saving measures; budget estimate.

### References

- Links to papers, docs, blog posts, prior art, and any external resources.

---

## Change Log

- v0.1 – Initial draft
- v0.2 – Architecture updated to match implementation
- v1.0 – Final version reflecting delivered system