🏗️ Architecture Documentation
Technical architecture guide for SpendWise application.
System Architecture Overview
SpendWise follows a modern mobile-first architecture with React Native (Expo) for the frontend and Firebase + Groq AI for backend services.
┌─────────────────────────────────────────────────────────────────────────┐
│ SPENDWISE ARCHITECTURE │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ 📱 PRESENTATION LAYER │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Dashboard │ │Transactions│ │ AI Insights│ │ Reports │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Budget │ │ Goals │ │ Settings │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
│ Expo Router (File-based) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 🧠 STATE MANAGEMENT LAYER │
│ │
│ AppContext (React Context API) │
│ ┌──────────────┬──────────────┬──────────────┬──────────────┐ │
│ │ Transactions │ Budgets │ Goals │ Settings │ │
│ └──────────────┴──────────────┴──────────────┴──────────────┘ │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ User │ Categories │ Currency │ │
│ └──────────────┴──────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ⚙️ SERVICE LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ lib/ │ │ lib/ │ │ lib/ │ │ lib/ │ │
│ │ auth.ts │ │ database.ts │ │ ai.ts │ │notifications │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ☁️ EXTERNAL SERVICES │
│ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ 🔐 Firebase Auth │ │ 🗄️ Firebase Realtime DB │ │
│ │ Email/Password │ │ Real-time sync │ │
│ │ Email verification │ │ Offline persistence │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
│ │
│ ┌────────────────────────────┐ ┌────────────────────────────┐ │
│ │ 🤖 Groq API │ │ 🔔 Expo Notifications │ │
│ │ LLaMA 3.3 70B │ │ Push notifications │ │
│ │ Financial insights │ │ Scheduled reminders │ │
│ └────────────────────────────┘ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Layer Architecture
Detailed breakdown of each application layer.
📱 1. Presentation Layer
React Native components with Expo Router for file-based navigation. Each screen is a self-contained module handling its own UI state and user interactions.
React Native Expo TypeScript react-native-chart-kit
app/
├── (auth)/
│ ├── _layout.tsx // Auth stack layout
│ └── login.tsx // Login/Register screen
│
├── (tabs)/
│ ├── _layout.tsx // Tab navigator (7 tabs)
│ ├── index.tsx // Dashboard
│ ├── transactions.tsx // Transaction list + CRUD
│ ├── insights.tsx // AI financial insights
│ ├── reports.tsx // Charts & analytics
│ ├── budget.tsx // Budget management
│ ├── goals.tsx // Savings goals
│ └── settings.tsx // App settings
│
└── _layout.tsx // Root layout with providers
🧠 2. State Management Layer
Global state managed via React Context API. The AppContext wraps the entire application and provides centralized state access and update functions.
React Context Custom Hooks useReducer
// context/AppContext.tsx
interface AppContextType {
// State
user: User | null;
transactions: Transaction[];
budgets: Budget[];
goals: Goal[];
categories: Category[];
currency: Currency;
darkMode: boolean;
// Actions
addTransaction: (t: Transaction) => Promise;
updateTransaction: (t: Transaction) => Promise;
deleteTransaction: (id: string) => Promise;
addBudget: (b: Budget) => Promise;
addGoal: (g: Goal) => Promise;
updateGoal: (g: Goal) => Promise;
setCurrency: (c: Currency) => Promise;
setDarkMode: (d: boolean) => Promise;
logout: () => Promise;
}
⚙️ 3. Service Layer
Abstraction layer for external service communication. Each service module handles a specific domain with proper error handling and type safety.
lib/auth.ts lib/database.ts lib/ai.ts lib/notifications.ts
// Service responsibilities
auth.ts → signUp, signIn, logout, resetPassword
database.ts → CRUD for transactions, budgets, goals, settings
→ Real-time subscriptions with onValue()
ai.ts → Groq API calls for financial insights
→ Response parsing and error handling
notifications.ts → Permission requests, channel setup
→ Immediate and scheduled notifications
☁️ 4. Data Layer - Firebase Schema
Firebase Realtime Database stores all user data with real-time synchronization across devices.
Firebase Auth Realtime Database Groq API
Firebase Realtime Database
│
├── users/{userId}/
│ │
│ ├── transactions/{transactionId}
│ │ ├── id: string
│ │ ├── type: "income" | "expense"
│ │ ├── amount: number
│ │ ├── category: string
│ │ ├── date: timestamp
│ │ ├── note: string
│ │ └── paymentMethod: string
│ │
│ ├── budgets/{budgetId}
│ │ ├── id: string
│ │ ├── category: string
│ │ ├── limit: number
│ │ └── period: "daily" | "weekly" | "monthly" | "yearly"
│ │
│ ├── goals/{goalId}
│ │ ├── id: string
│ │ ├── name: string
│ │ ├── targetAmount: number
│ │ ├── currentAmount: number
│ │ ├── deadline: timestamp
│ │ └── priority: "low" | "medium" | "high"
│ │
│ └── settings/
│ ├── currency: { code, symbol, name }
│ └── darkMode: boolean
Data Flow
How data moves through the application layers.
User Action
User taps "Add Transaction" button
Presentation Layer
Screen component calls addTransaction from AppContext
State Management
AppContext dispatches to service layer and updates local state
Service Layer
database.ts writes to Firebase, checks budgets for alerts
Firebase
Data persisted to Realtime Database, synced to other devices
Real-time Update
onValue listener triggers, state updates, UI re-renders
AI Integration Architecture
How Groq AI provides financial insights.
┌─────────────────────────────────────────────────────────────────────────┐
│ AI INSIGHTS FLOW │
└─────────────────────────────────────────────────────────────────────────┘
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Transactions │ │ Budgets │ │ Goals │
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ │ │
└──────────────────────┼──────────────────────┘
│
▼
┌──────────────────┐
│ Prepare Data │
│ - Filter 30d │
│ - Calculate │
│ summaries │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Build Prompt │
│ - System role │
│ - User data │
│ - JSON format │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Groq API │
│ LLaMA 3.3 70B │
│ POST /chat/ │
│ completions │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Parse Response │
│ - Extract JSON │
│ - Validate │
│ - fallbacks │
└────────┬─────────┘
│
▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Health Score │ │ Insights │ │Recommendations │
│ 0-100 │ │ (4 types) │ │ (actions) │
└────────────────┘ └────────────────┘ └────────────────┘
Push Notification Architecture
Notification Triggers
| Trigger | Condition | Notification |
|---|---|---|
| Budget 80% | Category spending ≥ 80% of limit | ⚠️ Warning alert |
| Budget 100% | Category spending ≥ 100% of limit | 🚨 Over budget alert |
| Daily Reminder | 8:00 PM daily (if enabled) | 📝 Log expenses reminder |
| Weekly Summary | Monday 9:00 AM (if enabled) | 📊 Weekly insights ready |
Security Architecture
Authentication Flow
┌─────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ User │────▶│ Login/ │────▶│ Firebase │────▶│ Verified │
│ │ │ Register │ │ Auth │ │ User │
└─────────┘ └─────────────┘ └──────────────┘ └──────────────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ Email │
└─────────────▶│ Verification │
└──────────────┘
Data Security
| Layer | Security Measure |
|---|---|
| API Keys | Environment variables (EXPO_PUBLIC_GROQ_API_KEY) |
| Firebase | User-scoped data (users/{userId}/...) |
| Auth | Email verification required before full access |
| Transport | HTTPS for all API calls |
Version Information
| Component | Version |
|---|---|
| SpendWise App | v2.1.0 |
| React Native | 0.76.5 |
| Expo SDK | 52 |
| Firebase | 11.0.2 |
| Groq Model | llama-3.3-70b-versatile |