# nerdylua/password-manager-web architecture

> Architecture diagram of the GitHub repository nerdylua/password-manager-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nerdylua/password-manager-web
- Repository: https://github.com/nerdylua/password-manager-web

## Overview

##### Project type and purpose
- This is a full-stack, client-heavy web application built with Next.js 15 (App Router) and TypeScript.
- It implements a zero-knowledge, end-to-end encrypted password manager (“CryptLock”) that uses Firebase for authentication and real-time data storage.
- Its core promise is that the master password never leaves the client, so all encryption/decryption happens in the browser.

##### File structure
- Top-level “app/” directory holds Next.js routes for auth (login/register/forgot-password), dashboard, vault, global layout and error pages.
- “components/” hosts reusable UI pieces, including shadcn/ui primitives under “components/ui”, custom modals, route guards, animations.
- “hooks/” contains React hooks: AuthContext for user state, a mobile-detection hook.
- “lib/” implements core logic: Firebase initialization, encryption utilities (PBKDF2, AES-256-CBC), vault-service (CRUD + sync), password strength analysis, generic helpers.
- Configuration files: next.config.ts, middleware.ts, Tailwind & PostCSS configs, tsconfig.json, ESLint config.
- Public assets under “public/”.
- Environment template and package manifests in root.

##### README for additional insights
- Tech stack: Next.js, Firebase Auth + Firestore + Hosting, CryptoJS, zxcvbn, React Hook Form, Tailwind CSS.
- Features emphasize offline support, real-time sync, route protection, cross-platform readiness.

##### Main components & interactions
a. Components
- User’s Browser & UI Layer (Next.js pages & React components)
- Frontend Service Layer (AuthContext, hooks, vault-service in lib/)
- Encryption Module (lib/encryption.ts + CryptoJS + PBKDF2)
- Firebase Services:
- Firebase Authentication
- Cloud Firestore
- Static Hosting / CDN (Vercel or Firebase Hosting)
- Optional: Local Cache (IndexedDB or in-memory for offline)
b. Relationships & Data Flow
- User ► enters master password ► Encryption Module ► derives key (PBKDF2) ► client-side encryption ► forms encrypted blob
- UI Layer ► calls vault-service ► writes/reads encrypted blob to/from Firestore
- AuthContext ► interacts with Firebase Auth ► provides JWT/session ► secured route access
- Firestore ► real-time sync pushes updates back to vault-service ► decryption then renders in UI
- Offline: service layer caches requests/blobs, syncs when online
c. Architectural Patterns & Principles
- Zero-Knowledge: encryption & decryption solely on client
- Separation of Concerns: UI components vs. service layer vs. crypto utils
- React Context for auth & session propagation
- Next.js App Router for SSR/CSR hybrid routing
- Component-based design (shadcn/ui primitives)
- Service abstraction (vault-service hides Firestore internals)
d. Key Technologies & Frameworks
- Next.js 15 (React, SSR/CSR)
- Firebase (Auth, Firestore, Hosting)
- CryptoJS & PBKDF2 for key derivation, AES-256-CBC encryption
- zxcvbn for password strength
- Tailwind CSS & shadcn/ui for styling
- React Hook Form for form state & validation
- Framer Motion for animations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Browser & UI Layer
    subgraph "User Browser & UI Layer"
        direction TB
        UB["User Browser"]:::external
        NextApp["Next.js App"]:::ui
        AuthPages["Auth Pages"]:::ui
        DashboardVault["Dashboard & Vault"]:::ui
        UIComponents["Reusable UI Components"]:::ui
        ShadcnPrimitives["shadcn/ui Primitives"]:::ui
    end

    %% Frontend Service Layer
    subgraph "Frontend Service Layer"
        direction TB
        AuthContext["AuthContext & Hooks"]:::service
        VaultService["Vault Service"]:::service
        OfflineCache["Offline Support (IndexedDB)"]:::service
    end

    %% Encryption Module
    subgraph "Encryption Module"
        direction TB
        Encryption["Encryption Module (PBKDF2 → AES-256-CBC)"]:::crypto
    end

    %% Firebase Services
    subgraph "Firebase Services"
        direction TB
        FirebaseAuth["Firebase Authentication"]:::external
        Firestore["Cloud Firestore"]:::db
    end

    %% Hosting & Deployment
    subgraph "Hosting & Deployment"
        direction TB
        Hosting["Vercel / Firebase Hosting"]:::external
    end

    %% Data Flow & Relationships
    UB -->|"HTTPS"| NextApp
    Hosting -->|"Serves App"| UB

    NextApp -->|"uses"| AuthPages
    NextApp -->|"uses"| DashboardVault
    NextApp -->|"renders"| UIComponents
    NextApp -->|"renders"| ShadcnPrimitives

    NextApp -->|"calls"| AuthContext
    NextApp -->|"calls"| VaultService

    AuthContext -->|"Auth Requests (JWT)"| FirebaseAuth
    VaultService -->|"Read/Write Encrypted Blob"| Firestore
    Firestore -->|"Real-time Sync"| VaultService

    UB -->|"enter Master Password"| Encryption
    Encryption -->|"derive key (PBKDF2)"| Encryption
    Encryption -->|"encrypt/decrypt data"| VaultService

    VaultService -->|"cache ops"| OfflineCache
    OfflineCache -->|"sync when online"| VaultService

    %% Click Events
    click NextApp "https://github.com/nerdylua/password-manager-web/blob/main/app/page.tsx"
    click NextApp "https://github.com/nerdylua/password-manager-web/blob/main/app/layout.tsx"
    click NextApp "https://github.com/nerdylua/password-manager-web/blob/main/app/globals.css"
    click NextApp "https://github.com/nerdylua/password-manager-web/blob/main/app/global-error.tsx"
    click NextApp "https://github.com/nerdylua/password-manager-web/blob/main/app/not-found.tsx"
    click AuthPages "https://github.com/nerdylua/password-manager-web/blob/main/app/auth/login/page.tsx"
    click AuthPages "https://github.com/nerdylua/password-manager-web/blob/main/app/auth/register/page.tsx"
    click AuthPages "https://github.com/nerdylua/password-manager-web/blob/main/app/auth/forgot-password/page.tsx"
    click AuthPages "https://github.com/nerdylua/password-manager-web/blob/main/app/auth/not-found.tsx"
    click DashboardVault "https://github.com/nerdylua/password-manager-web/blob/main/app/dashboard/page.tsx"
    click DashboardVault "https://github.com/nerdylua/password-manager-web/blob/main/app/vault/page.tsx"
    click UIComponents "https://github.com/nerdylua/password-manager-web/tree/main/components/"
    click ShadcnPrimitives "https://github.com/nerdylua/password-manager-web/tree/main/components/ui/"
    click AuthContext "https://github.com/nerdylua/password-manager-web/blob/main/hooks/AuthContext.tsx"
    click AuthContext "https://github.com/nerdylua/password-manager-web/blob/main/hooks/use-mobile.ts"
    click VaultService "https://github.com/nerdylua/password-manager-web/blob/main/lib/vault-service.ts"
    click Encryption "https://github.com/nerdylua/password-manager-web/blob/main/lib/encryption.ts"
    click FirebaseAuth "https://github.com/nerdylua/password-manager-web/blob/main/lib/firebase.ts"
    click FirebaseAuth "https://github.com/nerdylua/password-manager-web/blob/main/lib/auth-utils.ts"
    click FirebaseAuth "https://github.com/nerdylua/password-manager-web/blob/main/lib/firebase-errors.ts"
    click Firestore "https://github.com/nerdylua/password-manager-web/blob/main/lib/firebase.ts"
    click Firestore "https://github.com/nerdylua/password-manager-web/blob/main/lib/security-config.ts"
    click Firestore "https://github.com/nerdylua/password-manager-web/blob/main/lib/auth-debug.ts"
    click PasswordStrength "https://github.com/nerdylua/password-manager-web/blob/main/lib/password-strength.ts"
    click PasswordStrength "https://github.com/nerdylua/password-manager-web/blob/main/lib/password-strength.ts"
    click Utils "https://github.com/nerdylua/password-manager-web/blob/main/lib/utils.ts"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/middleware.ts"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/next.config.ts"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/tailwind.config.ts"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/postcss.config.mjs"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/tsconfig.json"
    click MiddlewareConfig "https://github.com/nerdylua/password-manager-web/blob/main/eslint.config.mjs"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/tree/main/public/"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/blob/main/package.json"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/blob/main/package-lock.json"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/blob/main/.env.example"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/blob/main/README.md"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/tree/main/LICENSE"
    click PublicAssets "https://github.com/nerdylua/password-manager-web/blob/main/.gitignore"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef service fill:#E8F1FF,stroke:#1C64F2,stroke-width:1px
    classDef crypto fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E2F0D9,stroke:#228B22,stroke-width:1px
    classDef db fill:#D5F5E3,stroke:#2E8B57,stroke-width:1px
    classDef cylinder fill:#FFF5BA,stroke:#DAA520,stroke-width:1px
```
