CONTEXT.md

Ganaka Expense Tracker - Complete Project Context

📋 Project Overview

Ganaka is a distributed, event-driven expense tracking system built with Rust using a microservices architecture. It provides comprehensive expense management with real-time analytics, intelligent categorization, and multi-channel notifications.

🎯 Core Purpose

• Track personal/business expenses with intelligent categorization
• Provide real-time analytics and reporting
• Enable multi-channel notifications for expense alerts
• Support real-time dashboard updates via WebSocket
• Ensure high performance with database partitioning and caching

🏗️ Architecture Philosophy

• Event-Driven: Services communicate via NATS messaging
• Domain-Driven Design: Each service owns specific business domains
• Scalability: Horizontal scaling with database partitioning
• Reliability: Fault-tolerant with circuit breakers and retries
• Observability: Comprehensive logging, metrics, and tracing

---

🛠️ Technology Stack

Backend Services

• Language: Rust 1.75+
• Web Framework: Axum 0.7 (async HTTP server)
• Database: PostgreSQL 15+ with partitioning
• Cache: Redis 7+ for sessions and caching
• Message Broker: NATS 2.9+ for event-driven communication
• ORM: SQLx 0.8 (compile-time verified queries)

Security & Authentication

• JWT: JSON Web Tokens for API authentication
• Password Hashing: Argon2 for secure password storage
• Session Management: Redis-based refresh token storage
• CORS: Configurable cross-origin resource sharing

Infrastructure & Deployment

• Containerization: Docker with multi-stage builds
• Orchestration: Docker Compose for development/production
• Monitoring: Prometheus + Grafana stack
• Logging: Loki + Promtail for centralized logging
• CI/CD: GitHub Actions workflows (disabled for portfolio project)

Testing & Quality

• Unit Tests: Rust built-in testing framework
• Integration Tests: Full service communication testing
• E2E Tests: Playwright for browser automation
• Performance Tests: k6 for load testing
• Code Quality: Clippy linting, security auditing

---

🏛️ System Architecture

Service Topology

┌─────────────────┐    ┌─────────────────┐
│   API Gateway   │    │  Auth Service   │
│     (Future)    │◄──►│   (Port 3001)   │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│  User Service   │    │Expense Service  │
│   (Port 3002)   │◄──►│  (Port 3003)    │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│Category Service │    │ Report Service  │
│  (Port 3004)    │◄──►│  (Port 3005)    │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│Notification Svc │    │Dashboard Service│
│  (Port 3006)    │◄──►│  (Port 3007)    │
└─────────────────┘    └─────────────────┘

Data Flow Patterns

User Registration Flow

1. Auth Service receives registration request
2. Creates user in database with hashed password
3. Publishes user.registered event to NATS
4. User Service consumes event and performs initialization
5. Category Service creates default categories for new user
6. Notification Service sends welcome message

Expense Creation Flow

1. Expense Service receives expense creation request
2. Validates and stores expense in partitioned table
3. Publishes expense.added event
4. Category Service attempts auto-categorization
5. Report Service updates analytics and publishes report.updated
6. Dashboard Service broadcasts real-time updates via WebSocket
7. Notification Service sends alerts for high-value expenses

---

🔧 Service Breakdown

1. Auth Service (Port 3001)

Purpose: User authentication and session management Responsibilities:

• User registration and login
• JWT token generation and validation
• Refresh token management via Redis
• Password hashing with Argon2
• Authentication middleware for protected routes

Key Endpoints:

• POST /auth/register - User registration
• POST /auth/login - User authentication
• POST /auth/refresh - Token refresh
• POST /auth/logout - Session termination
• GET /auth/me - Current user info (protected)

2. User Service (Port 3002)

Purpose: User profile management Responsibilities:

• User CRUD operations
• Profile updates and preferences
• User data validation
• Event consumption for user lifecycle

Key Endpoints:

• GET /users/{id} - Get user profile
• PUT /users/{id} - Update user profile
• DELETE /users/{id} - Delete user account

3. Expense Service (Port 3003)

Purpose: Core expense management Responsibilities:

• Expense CRUD operations
• Database partitioning by user_id
• Expense validation and business rules
• Event publishing for expense lifecycle

Key Endpoints:

• GET /expenses - List user expenses (paginated)
• POST /expenses - Create new expense
• GET /expenses/{id} - Get specific expense
• PUT /expenses/{id} - Update expense
• DELETE /expenses/{id} - Delete expense

4. Category Service (Port 3004)

Purpose: Expense categorization and organization Responsibilities:

• Category CRUD operations
• Auto-categorization based on keywords
• Default category creation for new users
• Category-based analytics

Key Endpoints:

• GET /categories - List user categories
• POST /categories - Create category
• PUT /categories/{id} - Update category
• DELETE /categories/{id} - Delete category

5. Report Service (Port 3005)

Purpose: Analytics and reporting Responsibilities:

• Monthly expense summaries
• Category spending analysis
• Materialized views for performance
• Real-time report generation

Key Endpoints:

• GET /reports/monthly/{year}/{month} - Monthly report
• GET /reports/categories/{year}/{month} - Category analysis
• GET /reports/summary - Overall spending summary

6. Notification Service (Port 3006)

Purpose: Multi-channel notifications Responsibilities:

• Email and SMS notifications
• Welcome messages for new users
• Expense alerts for high-value transactions
• Monthly report summaries

Key Features:

• SMTP email integration
• SMS provider integration (configurable)
• Template-based message generation
• Notification history tracking

7. Dashboard Service (Port 3007)

Purpose: Real-time dashboard and WebSocket updates Responsibilities:

• Live expense tracking
• WebSocket connections for real-time updates
• Dashboard data aggregation
• Cache management for performance

Key Features:

• WebSocket endpoint for live updates
• Dashboard summary generation
• Real-time expense notifications
• Cache invalidation and updates

---

📊 Data Architecture

Database Schema

Core Tables

-- Users with preferences
users (
    id UUID PRIMARY KEY,
    email VARCHAR UNIQUE,
    name VARCHAR,
    role user_role,
    preferences JSONB,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
)

-- Secure password storage
user_passwords (
    user_id UUID PRIMARY KEY,
    password_hash VARCHAR
)

-- Partitioned expenses for scalability
expenses (
    id UUID PRIMARY KEY,
    user_id UUID,
    amount DECIMAL(12,2),
    description TEXT,
    category_id UUID,
    timestamp TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
) PARTITION BY HASH (user_id)

-- User-defined categories
categories (
    id UUID PRIMARY KEY,
    user_id UUID,
    name VARCHAR,
    description TEXT,
    UNIQUE(user_id, name)
)

-- Notification history
notifications (
    id UUID PRIMARY KEY,
    user_id UUID,
    channel notification_channel,
    message TEXT,
    sent_at TIMESTAMP
)

Performance Optimizations

• Hash Partitioning: Expenses table partitioned by user_id (16 partitions)
• Materialized Views: Pre-computed monthly and category summaries
• Indexes: Optimized for common query patterns
• Connection Pooling: Configured for high concurrency

Caching Strategy

• Redis: Session storage, refresh tokens, dashboard cache
• TTL: 24 hours for dashboard data, 30 days for sessions
• Invalidation: Event-driven cache updates

---

🔄 Event-Driven Communication

NATS Subjects and Events

User Lifecycle Events

• user.registered - New user registration
• user.logged_in - User authentication
• user.logged_out - User session termination

Expense Events

• expense.added - New expense created
• expense.updated - Expense modified
• expense.deleted - Expense removed
• expense.categorized - Expense category assigned

Analytics Events

• report.updated - Report data refreshed
• category.created - New category added

Notification Events

• notification.sent - Notification delivered

Event Processing Patterns

• Fire-and-Forget: Most events are processed asynchronously
• At-Least-Once Delivery: Guaranteed event processing
• Event Sourcing: Audit trail via event logs
• Circuit Breaker: Fault tolerance for service communication

---

🔐 Security Design

Authentication Flow

1. Registration: Password hashed with Argon2, stored separately
2. Login: Password verification, JWT + refresh token generation
3. Session Management: Refresh tokens stored in Redis with TTL
4. Middleware: JWT validation on protected routes

Security Measures

• Password Security: Argon2 hashing with salt
• Token Security: Short-lived access tokens (15min), longer refresh tokens (30 days)
• Input Validation: Comprehensive validation on all endpoints
• CORS Configuration: Restrictive cross-origin policies
• SQL Injection Prevention: SQLx compile-time query verification

---

🚀 Development Setup

Prerequisites

• Rust: 1.75+ with Cargo
• Docker: 24+ with Docker Compose
• PostgreSQL: 15+ (via Docker)
• Redis: 7+ (via Docker)
• NATS: 2.9+ (via Docker)

Local Development

# Clone repository
git clone <repository-url>
cd ganaka

# Start infrastructure
docker-compose -f docker-compose.dev.yml up -d

# Run all services
./scripts/run-dev.sh

# Or run individual services
cargo run --bin auth-service
cargo run --bin user-service
cargo run --bin docs-aggregator
# ... etc

Environment Variables

# Database
DATABASE_URL=postgres://user:password@localhost:5432/ganaka

# Cache
REDIS_URL=redis://localhost:6379

# Messaging
NATS_URL=nats://localhost:4222

# Security
JWT_SECRET=your-256-bit-secret-key

# Email (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

---

🧪 Testing Strategy

Test Pyramid

• Unit Tests: Individual functions and modules (80%)
• Integration Tests: Service-to-service communication (15%)
• E2E Tests: Full user workflows (5%)

Test Categories

• API Tests: REST endpoint validation
• Database Tests: Data persistence and queries
• Event Tests: Message publishing and consumption
• Performance Tests: Load testing with k6
• Security Tests: Authentication and authorization

Test Execution

# Unit tests
cargo test --workspace

# Integration tests
cargo test --test integration_test

# E2E tests
cd tests/e2e && npm test

# Performance tests
k6 run tests/performance/k6-script.js

---

📦 Deployment Architecture

Development Environment

• Docker Compose: Single-command infrastructure setup
• Hot Reload: Cargo watch for service development
• Local Services: All dependencies run in containers

Production Environment

• Containerized: Each service in optimized Docker image
• Orchestration: Kubernetes manifests (planned)
• Load Balancing: Nginx or service mesh
• Monitoring: Prometheus + Grafana + Loki stack

CI/CD Pipeline (Disabled)

1. Lint & Test: Code quality and unit tests
2. Build: Docker images for all services
3. Security Scan: Dependency vulnerability checks
4. Deploy: Environment-specific deployments
5. Monitor: Health checks and alerting

Note: Workflows are present but disabled (if: false) as this is a portfolio project with no deployment target.

---

📈 Performance Characteristics

Scalability Features

• Database Partitioning: Horizontal scaling by user
• Connection Pooling: Optimized database connections
• Caching Layers: Redis for frequently accessed data
• Async Processing: Non-blocking I/O throughout

Performance Targets

• API Response Time: <100ms for 95% of requests
• Concurrent Users: 10,000+ simultaneous connections
• Database Queries: <10ms average response time
• Event Processing: <1 second end-to-end latency

Monitoring Metrics

• Service Health: Uptime and response times
• Database Performance: Query execution times
• Event Throughput: Messages per second
• Error Rates: 4xx/5xx response percentages

---

🔮 Future Enhancements

Planned Features

• API Gateway: Centralized request routing and authentication
• Kubernetes Deployment: Production container orchestration
• Advanced Observability: Distributed tracing with OpenTelemetry
• Machine Learning: AI-powered expense categorization
• Mobile App: React Native companion application
• Multi-Tenancy: Organization and team support

Technical Roadmap

• Service Mesh: Istio integration for advanced networking
• Event Sourcing: Complete audit trail and replay capabilities
• CQRS Pattern: Separate read/write models for complex queries
• GraphQL API: Flexible query interface for advanced clients

---

🤝 Development Guidelines

Code Standards

• Rust Edition: 2021 with strict Clippy rules
• Error Handling: Custom error types with thiserror
• Logging: Structured logging with tracing
• Documentation: Comprehensive docs.rs documentation

Commit Conventions

• Conventional Commits: feat:, fix:, docs:, refactor:
• Atomic Commits: Single responsibility per commit
• Descriptive Messages: Clear explanation of changes

Branch Strategy

• main: Production-ready code
• develop: Integration branch
• feature/*: Feature development branches
• hotfix/*: Critical bug fixes

---

📚 Key Design Decisions

Why Rust?

• Performance: Zero-cost abstractions, memory safety
• Reliability: Compile-time guarantees, no runtime panics
• Scalability: Async runtime optimized for concurrency
• Ecosystem: Rich crate ecosystem for production use

Why Microservices?

• Domain Isolation: Clear boundaries between business concerns
• Independent Scaling: Scale services based on load patterns
• Technology Diversity: Choose best tool for each domain
• Fault Isolation: Service failures don't cascade

Why Event-Driven?

• Loose Coupling: Services communicate via events, not direct calls
• Scalability: Asynchronous processing handles load spikes
• Auditability: Complete event history for debugging
• Extensibility: New services can consume existing events

Why PostgreSQL Partitioning?

• Performance: Faster queries on partitioned data
• Scalability: Distribute data across multiple disks/nodes
• Maintenance: Easier backup and archiving of old data
• Cost Efficiency: Optimize storage based on access patterns

---

🚨 Troubleshooting Guide

Common Issues

Service Won't Start

• Check Environment: Verify all required environment variables
• Check Dependencies: Ensure PostgreSQL, Redis, NATS are running
• Check Ports: Verify no port conflicts (3001-3007)
• Check Logs: Use RUST_LOG=debug for detailed logging

Database Connection Issues

• Verify Connection String: Check DATABASE_URL format
• Check PostgreSQL: Ensure database exists and is accessible
• Check Migrations: Run database migrations if needed

Event Processing Issues

• Check NATS: Verify NATS server is running on port 4222
• Check Subjects: Verify correct event subjects are being used
• Check Serialization: Ensure event payloads can be deserialized

Performance Issues

• Check Database Indexes: Verify proper indexing on frequently queried columns
• Check Connection Pooling: Ensure adequate connection pool size
• Check Caching: Verify Redis is being used effectively

---

📞 Support and Resources

Documentation

• OpenAPI Specs: Each service exposes /api-docs endpoint for live OpenAPI JSON specs
• Docs Aggregator: docs-aggregator service (port 3008) provides /services endpoint listing all service docs URLs
• Architecture Guide: /docs/architecture/ - System design decisions
• Developer Guide: /docs/developer-guide/ - Development setup and guidelines

Development Resources

• Scripts: /scripts/ - Development helper scripts
• Tests: /tests/ - Comprehensive test suites
• Infrastructure: /infrastructure/ - Deployment configurations

External Dependencies

• Rust Documentation: https://doc.rust-lang.org/
• Axum Framework: https://docs.rs/axum/
• SQLx Documentation: https://docs.rs/sqlx/
• NATS Documentation: https://docs.nats.io/

---

This context file provides complete understanding of the Ganaka expense tracker project. Any AI or developer should be able to understand the system architecture, implementation details, and development processes from this single document.