# apurv212/secure-ai-vault architecture

> Architecture diagram of the GitHub repository apurv212/secure-ai-vault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apurv212/secure-ai-vault
- Repository: https://github.com/apurv212/secure-ai-vault

## Overview

##### Project Type and Purpose
- Type: Full-stack web application
- Purpose: Securely store and manage card details with AI-powered extraction, automatic categorization, and Firebase-backed persistence.

##### File Structure
Top-level:
– client/ → React + TypeScript + Vite frontend
– server/ → Node.js + Express backend
Frontend:
– src/components → UI components (features, layout, pages, ui)
– src/contexts, src/store → state and context management
– src/services/api.ts → REST client for server
– firebase/config.ts → Firebase Auth, Firestore, Storage setup
Backend:
– index.js → Express app entrypoint
– routes/*.js → API endpoints (auth, cards, extract)
– utils/*.js → helper modules (bank normalization, encryption, rate limiting, secure logging, image encryption)
Shared:
– package.json scripts for install-all, dev tasks
– .env files for credentials

##### README for Additional Insights
- External AI services: gemini, deepseek, marker
- Firebase services: Auth, Firestore, Storage
- API URL: /api on port 5000
- Frontend served on port 3000

##### Main Components and Their Interactions
a. Frontend (React + Vite)
– UI Layer: Pages (Login, Dashboard), Feature components (CardUpload, CardItem), Layout components (Header, Sidebar)
– State Layer: Context (AuthContext), Redux-style store slices (theme, cards)
– Service Layer: api.ts calls backend REST endpoints
– Firebase SDK: Auth, Firestore reads/writes, Storage for uploaded images
b. Backend (Express)
– API Layer: auth.js (signup/login), cards.js (CRUD), extract.js (AI extraction orchestration)
– Business Logic: imageEncryption, encryption (securely store card data), bankNormalizer
– External AI Services: gemini, deepseek, marker invoked within extract route
– Rate Limiter & Secure Logger middleware
c. Data Stores
– Firebase Firestore: card metadata, user profiles
– Firebase Storage: raw images for OCR/extraction
d. External Services
– gemini, deepseek, marker AI APIs for OCR and data extraction

##### Architectural Patterns and Design Principles
- Layered Architecture: UI → State → Services → API → Business Logic → Data
- Separation of Concerns: frontend vs. backend responsibilities
- Single REST monolith on backend with modular routes
- Cloud-native services (Firebase managed by client)
- Secure handling: encryption utils, no CVV storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Entry
    Browser["User Browser"]:::browser

    %% Frontend Layer
    subgraph "Frontend (React + Vite)" 
        direction TB
        App["App.tsx"]:::frontend
        Index["index.tsx"]:::frontend
        subgraph "UI Layer"
            direction TB
            Pages["Pages (Login, Dashboard)"]:::frontend
            Features["Features (CardUpload, CardItem, ManualEntryModal)"]:::frontend
            Layout["Layout (Header, Sidebar)"]:::frontend
            UIElements["UI Elements (buttons, inputs, spinner)"]:::frontend
        end
        subgraph "State Layer"
            direction TB
            AuthContext["AuthContext"]:::frontend
            Store["Redux Store"]:::frontend
            Hooks["Store Hooks"]:::frontend
            ThemeSlice["themeSlice"]:::frontend
        end
        subgraph "Service Layer"
            direction TB
            APIService["api.ts"]:::frontend
        end
        subgraph "Firebase SDK"
            direction TB
            FirebaseConfig["config.ts"]:::frontend
        end
        subgraph "Frontend Utils"
            direction TB
            FEUtils["utils (cardUtils, imageCompression, storage)"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Express)" 
        direction TB
        Server["index.js"]:::backend
        subgraph "API Routes"
            direction TB
            AuthRoute["auth.js"]:::backend
            CardsRoute["cards.js"]:::backend
            ExtractRoute["extract.js"]:::backend
        end
        subgraph "Business Logic & Middleware"
            direction TB
            BankNorm["bankNormalizer.js"]:::backend
            Encryption["encryption.js"]:::backend
            ImageEnc["imageEncryption.js"]:::backend
            RateLimiter["rateLimiter.js"]:::backend
            SecureLogger["secureLogger.js"]:::backend
        end
    end

    %% Data Stores
    subgraph "Data Stores" 
        direction TB
        Firestore["Firestore"]:::datastore
        Storage["Firebase Storage"]:::datastore
    end

    %% External AI Services
    subgraph "External AI Services" 
        direction TB
        Gemini["Gemini"]:::external
        Deepseek["Deepseek"]:::external
        Marker["Marker"]:::external
    end

    %% Connections
    Browser -->|"loads"| App
    App -->|"renders UI"| Pages
    Pages --> Features
    Pages --> Layout
    Pages --> UIElements
    App --> AuthContext
    AuthContext --> Store
    Store --> Hooks
    Store --> ThemeSlice
    App --> APIService
    APIService -->|"REST /api calls"| AuthRoute
    APIService --> CardsRoute
    APIService --> ExtractRoute
    App --> FirebaseConfig
    App --> FEUtils

    Server --> AuthRoute
    Server --> CardsRoute
    Server --> ExtractRoute

    AuthRoute --> BankNorm
    CardsRoute --> Encryption
    ExtractRoute --> ImageEnc
    ExtractRoute --> Gemin       

    ExtractRoute --> Gemini
    ExtractRoute --> Deepseek
    ExtractRoute --> Marker

    AuthRoute --> Firestore
    CardsRoute --> Firestore
    ExtractRoute --> Storage

    ExtractRoute --> RateLimiter
    ExtractRoute --> SecureLogger

    %% Click Events
    click Pages "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/pages/Login.tsx"
    click Pages "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/pages/Dashboard.tsx"
    click Features "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/features/cards/CardUpload.tsx"
    click Features "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/features/cards/CardItem.tsx"
    click Features "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/features/cards/ManualEntryModal.tsx"
    click Layout "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/layout/Header.tsx"
    click Layout "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/components/layout/Sidebar.tsx"
    click UIElements "https://github.com/apurv212/secure-ai-vault/tree/main/client/src/components/ui"
    click AuthContext "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/contexts/AuthContext.tsx"
    click Store "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/store/index.ts"
    click Hooks "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/store/hooks.ts"
    click ThemeSlice "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/store/slices/themeSlice.ts"
    click APIService "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/services/api.ts"
    click FirebaseConfig "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/firebase/config.ts"
    click FEUtils "https://github.com/apurv212/secure-ai-vault/tree/main/client/src/utils"
    click App "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/App.tsx"
    click Index "https://github.com/apurv212/secure-ai-vault/blob/main/client/src/index.tsx"
    click Server "https://github.com/apurv212/secure-ai-vault/blob/main/server/index.js"
    click AuthRoute "https://github.com/apurv212/secure-ai-vault/blob/main/server/routes/auth.js"
    click CardsRoute "https://github.com/apurv212/secure-ai-vault/blob/main/server/routes/cards.js"
    click ExtractRoute "https://github.com/apurv212/secure-ai-vault/blob/main/server/routes/extract.js"
    click BankNorm "https://github.com/apurv212/secure-ai-vault/blob/main/server/utils/bankNormalizer.js"
    click Encryption "https://github.com/apurv212/secure-ai-vault/blob/main/server/utils/encryption.js"
    click ImageEnc "https://github.com/apurv212/secure-ai-vault/blob/main/server/utils/imageEncryption.js"
    click RateLimiter "https://github.com/apurv212/secure-ai-vault/blob/main/server/utils/rateLimiter.js"
    click SecureLogger "https://github.com/apurv212/secure-ai-vault/blob/main/server/utils/secureLogger.js"

    %% Styles
    classDef browser fill:#D0E7FF,stroke:#4A90E2,stroke-width:1px
    classDef frontend fill:#E3F2FD,stroke:#1976D2,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
    classDef datastore fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:1px
```
