# pendhrdream/wallet architecture

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

- Interactive diagram: https://gitdiagram.com/pendhrdream/wallet
- Repository: https://github.com/pendhrdream/wallet

## Overview

##### Project type and purpose
- This is a full-stack web application (“Verifiable Credential Wallet”) composed of a React/TailwindCSS frontend and an Express/TypeScript backend.
- It allows users to issue, list, share, verify, and delete verifiable credentials stored in JSON files.

##### File structure
- Top-level services:
- frontend/ – React UI built with Vite, TailwindCSS, served in dev by Vite or in production by Nginx.
- backend/ – Express API written in TypeScript, with modules for crypto, JSON Canonicalization Scheme (JCS), routes, and storage.
- data/ – Persistent JSON storage (credentials.json, keys.json).
- docker-compose.yml – Defines multi-container setup.
- Build and deployment: Dockerfiles in both frontend/ and backend/, plus Kubernetes-style orchestration via docker-compose.
- Configuration: .env.example files, tsconfig.json in both codebases, nginx.conf for frontend reverse proxy.

##### README for additional insights
- Confirms ports: frontend on 5173 (dev) or 80 (prod), backend on 3000.
- Lists API endpoints (POST /api/credentials, GET /api/verify, etc.).
- Emphasizes containerized vs. local dev workflows.

a. Main components:
- Client Browser (UI)
- Frontend Service
– Vite Dev Server (dev) / Nginx + static assets (prod)
– React components, API client
- Backend Service
– Express + TypeScript server
– Route handlers (Issue, Verify, List, Delete)
– Crypto & JCS modules
– Storage module (reads/writes JSON files)
- Data Store
– JSON files in data/ (credentials.json, keys.json)
- Orchestration
– Docker Compose, volumes, environment variables
b. Component interactions:
1. User → Browser UI
2. Browser → Frontend (HTTP on 5173 or 80)
3. Frontend → Backend (HTTP on 3000, proxy via vite.config.ts or nginx.conf)
4. Backend → Data Store (local file I/O)
5. (Optional) Backend health checks
c. Architectural patterns and principles:
- Separation of concerns: clear frontend/backend split
- Single-page application (SPA) communicating via RESTful JSON API
- Modular backend design (routes, crypto, storage modules)
- Containerization for environment parity
d. Key technologies and frameworks:
- Frontend: React, Vite, TypeScript, TailwindCSS, Nginx
- Backend: Node.js, Express, TypeScript, JCS, custom crypto logic
- Persistence: File-based JSON storage
- DevOps: Docker, Docker Compose

##### Essential architectural elements
- Clearly separate presentation (React), business logic (Express routes + crypto), and persistence (JSON files).
- How Docker Compose ties together the two containers and mounts the data volume.
- Nginx reverse proxy layer when illustrating production deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Client Browser"]:::external

    subgraph "Docker Compose Environment" 
        direction TB
        subgraph "Frontend Service" 
            direction TB
            subgraph "Dev/Prod Server"
                Vite["Vite Dev Server (5173)"]:::frontend
                Nginx["Nginx + Static Assets (80)"]:::frontend
            end
            subgraph "React Application"
                ReactMain["main.tsx"]:::frontend
                App["App.tsx"]:::frontend
                Components["Components"]:::frontend
                APIClient["api.ts"]:::api
                Hook["useCredentials.ts"]:::frontend
                Tailwind["tailwind.config.js"]:::config
                PostCSS["postcss.config.js"]:::config
            end
        end

        subgraph "Backend Service"
            direction TB
            Server["server.ts"]:::backend
            Routes["routes.ts"]:::backend
            Crypto["crypto.ts"]:::backend
            JCS["jcs.ts"]:::backend
            Storage["storage.ts"]:::backend
            Types["types.ts"]:::backend
            Tests["__tests__"]:::backend
            EnvExample[".env.example"]:::config
        end

        DataStore["JSON Files\n(credentials.json, keys.json)"]:::db
    end

    Browser -->|"HTTP 5173/80"| Vite
    Browser -->|"HTTP 80"| Nginx
    Vite --> ReactMain
    Nginx --> ReactMain
    ReactMain --> App
    App --> Components
    App --> APIClient
    APIClient -->|"REST API\n(port 3000)"| Server
    Server --> Routes
    Routes --> Crypto
    Routes --> JCS
    Routes --> Storage
    Crypto --> Types
    JCS --> Types
    Storage --> Types
    Storage --> DataStore

    classDef frontend fill:#D6EAF8,stroke:#2980B9
    classDef backend fill:#D5F5E3,stroke:#27AE60
    classDef db fill:#FAD7A0,stroke:#DC7633
    classDef orchestration fill:#f2f2f2,stroke:#888
    classDef external fill:#F0F0F0,stroke:#666
    classDef api fill:#AED6F1,stroke:#3498DB
    classDef config fill:#FCF3CF,stroke:#F1C40F

    click Vite "https://github.com/pendhrdream/wallet/blob/main/frontend/vite.config.ts"
    click Nginx "https://github.com/pendhrdream/wallet/blob/main/frontend/nginx.conf"
    click Nginx "https://github.com/pendhrdream/wallet/tree/main/frontend/Dockerfile"
    click ReactMain "https://github.com/pendhrdream/wallet/blob/main/frontend/src/main.tsx"
    click App "https://github.com/pendhrdream/wallet/blob/main/frontend/src/App.tsx"
    click Components "https://github.com/pendhrdream/wallet/tree/main/frontend/src/components"
    click APIClient "https://github.com/pendhrdream/wallet/blob/main/frontend/src/api.ts"
    click Hook "https://github.com/pendhrdream/wallet/blob/main/frontend/src/hooks/useCredentials.ts"
    click Tailwind "https://github.com/pendhrdream/wallet/blob/main/frontend/tailwind.config.js"
    click PostCSS "https://github.com/pendhrdream/wallet/blob/main/frontend/postcss.config.js"
    click Server "https://github.com/pendhrdream/wallet/blob/main/backend/src/server.ts"
    click Routes "https://github.com/pendhrdream/wallet/blob/main/backend/src/routes.ts"
    click Crypto "https://github.com/pendhrdream/wallet/blob/main/backend/src/crypto.ts"
    click JCS "https://github.com/pendhrdream/wallet/blob/main/backend/src/jcs.ts"
    click Storage "https://github.com/pendhrdream/wallet/blob/main/backend/src/storage.ts"
    click Types "https://github.com/pendhrdream/wallet/blob/main/backend/src/types.ts"
    click Tests "https://github.com/pendhrdream/wallet/tree/main/backend/src/__tests__"
    click EnvExample "https://github.com/pendhrdream/wallet/blob/main/backend/.env.example"
    click DataStore "https://github.com/pendhrdream/wallet/tree/main/data"
    click compose "https://github.com/pendhrdream/wallet/blob/main/docker-compose.yml"
    click backendDocker "https://github.com/pendhrdream/wallet/tree/main/backend/Dockerfile"
    click docs "https://github.com/pendhrdream/wallet/blob/main/docs/architecture.md"
```
