🏛️ System Architecture Deep Dive

WealthFam is designed as a modular microservice ecosystem. Each component is decoupled, allowing for independent scaling, maintenance, and deployment.

---

🧩 Architectural Philosophy

• Modularity: Every service (Backend, Frontend, Parser, Mobile) functions as an isolated unit.
• Local-First Database: Data is stored in high-performance DuckDB instances, ensuring privacy and speed.
• Precision Accuracy: Every transaction is hashed (MD5/SHA256) and anchored with metadata to ensure it cannot be duplicated or lost.

---

📡 Core Components

1. The API Gateway (Backend)

• Role: Central nervous system.
• Tech: FastAPI (Python).
• Function: Manages the DuckDB connection, authenticates users, and orchestrates requests between the Frontend and the Parser.

2. The Ingestion Engine (Parser)

• Role: Data harvester.
• Tech: Python, Regular Expressions, Gemini AI.
• Function: Receives raw data (SMS, Emails, PDFs) and converts it into structured Transactional JSON.

3. The WealthHub (Frontend)

• Role: Command center.
• Tech: Vue 3, Vite, Tailwind CSS.
• Function: Provides the Material 3 dashboard for visualizing wealth, managing budgets, and analyzing spending patterns.

4. Precision Pulse (Mobile)

• Role: Real-time sensor.
• Tech: Flutter (Android).
• Function: Native SMS background listener that captures transaction alerts the moment they arrive.

---

🔄 Data Lifecycle & Synchronization

sequenceDiagram
    participant S as Source (SMS/Mail)
    participant P as Parser Engine
    participant B as FastAPI Backend
    participant D as DuckDB Storage
    participant F as Vue Frontend

    Note over S, P: Data Capture
    S->>P: Raw Alert (Unstructured)
    
    Note over P: Deduplication & Parsing
    P->>P: MD5 Hashing
    P->>P: Dynamic Pattern Matching
    P-->>P: AI Fallback (Gemini)
    
    Note over P, B: Normalization
    P->>B: Structured Transaction JSON
    
    Note over B, D: Persistence
    B->>D: SQL Upsert
    D-->>B: Confirmation
    
    Note over B, F: Visualization
    B->>F: Real-time API Push / Pull
    F->>F: M3 Dashboard Render

---

🛡️ Security & Privacy

WealthFam implements a Sovereign Circle model:

1. Isolation: Your backend instance is yours. It doesn't talk to other users' backends.
2. Encryption: Data at rest can be encrypted, and all communication between services uses TLS (when deployed) or local socket isolation.
3. Audit Logs: Every change to a transaction is logged with a versioned history.

---

*Architecture for a Lifetime · Privacy by Design · Precision by Heart*