# whisperrnote/auth architecture

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

- Interactive diagram: https://gitdiagram.com/whisperrnote/auth
- Repository: https://github.com/whisperrnote/auth

## Overview

##### Project Type and Purpose
- Whisperrauth is a full-stack, zero-knowledge password manager built with Next.js for the front-end and Appwrite as a Backend-as-a-Service.
- It provides secure, client-side encryption; user authentication (email/password, magic links, OTP, TOTP); credential storage; and sync across devices.

##### File Structure
- **app/** – Next.js 13 “app router” directory. Contains page.tsx files for each route (/, /login, /register, /credentials, /forgot-password, /reset-password, /settings, /totp).
- **components/** – Reusable UI primitives (Button, Card, DropdownMenu, Input) and layout (AppShell, Header).
- **lib/** – Utility modules: Appwrite client initializer (`appwrite.ts`), shared helper functions (`utils.ts`).
- Configuration: `.env.sample` (Appwrite endpoint, project ID, collection IDs), `next.config.ts`, `tsconfig.json`, `postcss.config.mjs`.

##### README for Context
- Confirms the Next.js + Appwrite stack.
- Details features: zero-knowledge encryption (client-side), password generator, biometric login hooks, automatic syncing, TOTP generator, magic link & OTP flows.
- Mentions environment variables required to connect to Appwrite.

a. Main Components
- Client (Browser/Mobile/WebView)
- Next.js Application (Server-Side Rendering + API Routes + Client Bundle)
- Appwrite Backend (Authentication Service, Database, Storage)
- Zero-Knowledge Crypto Module (in-browser encryption/decryption)
- TOTP Generator Module (in-browser)
- External Services (e.g., CDN, Analytics – optional)

b. Relationships & Data Flows
1. **User Interaction**
- User visits Next.js pages (login/register/credentials).
- Inputs credentials or uses magic link/OTP.
2. **Authentication**
- Next.js invokes Appwrite Auth SDK via REST or JS SDK.
- Appwrite issues JWT/session cookie.
3. **Zero-Knowledge Encryption**
- On “save credential,” front-end uses the crypto module to encrypt data before sending to Appwrite database.
- On “view credential,” encrypted blob fetched from Appwrite, then decrypted client-side.
4. **TOTP Flow**
- User enables TOTP: front-end generates secret, shows QR.
- On login with TOTP, front-end validates code locally or via Appwrite function.
5. **Sync**
- Data changes trigger push to Appwrite; other clients pull updates on next launch or via real-time subscription.

c. Architectural Patterns & Principles
- **Zero-Trust / Zero-Knowledge**: all sensitive operations (encrypt/decrypt) happen on the client.
- **Serverless / BaaS**: Appwrite handles authentication, database, storage, and functions – no custom back-end servers needed.
- **Componentization**: UI and utility layers are modular (clear separation).
- **Next.js App Router**: server and client components co-located by route under `app/`.

d. Key Technologies
- Next.js 13 (React, App Router, SSR/SSG)
- Appwrite JS SDK (auth, database, storage)
- Tailwind CSS (styling)
- TypeScript (static typing)
- Web Crypto API or custom libs in `lib/utils.ts` for encryption

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Device Layer
    subgraph "User Device"
        Browser["Browser/Mobile App"]:::client
        subgraph "Next.js Application"
            Providers["Global Providers"]:::frontend
            subgraph "Pages"
                Root["Root Page"]:::frontend
                Login["Login Page"]:::frontend
                OTP["OTP Login Sub-Flow"]:::frontend
                Register["Register Page"]:::frontend
                Forgot["Forgot Password Page"]:::frontend
                Reset["Reset Password Page"]:::frontend
                CredList["Credentials List Page"]:::frontend
                NewCred["New Credential Entry Page"]:::frontend
                Folders["Folders View Page"]:::frontend
                Settings["Settings Page"]:::frontend
                TOTPPage["TOTP Setup & Validation Page"]:::frontend
            end
            subgraph "UI Components"
                AppShell["App Shell Layout"]:::component
                Header["Header Layout"]:::component
                Button["Button"]:::component
                Card["Card"]:::component
                Dropdown["Dropdown Menu"]:::component
                Input["Input Field"]:::component
            end
            Crypto["Zero-Knowledge Crypto Module"]:::crypto
            TOTPMod["TOTP Generator Module"]:::crypto
        end
    end

    %% Appwrite BaaS Layer
    subgraph "Appwrite BaaS"
        Auth["Authentication Service"]:::backend
        Database["Database"]:::db
        Storage["Storage"]:::db
    end

    %% Utils & Configuration
    subgraph "Utilities & Config"
        AppwriteClient["Appwrite Client Initializer"]:::backend
        Utils["Zero-Knowledge Crypto & Helpers"]:::crypto
        Static["Static Assets"]:::config
        Env["Environment Template']"]:::config
        NextConfig["Next.js Configuration"]:::config
        Globals["Global Stylesheet"]:::config
    end

    %% Flows
    Browser -->|"visit pages"| Providers
    Providers -->|"renders"| Root
    Providers -->|"renders"| Login
    Providers -->|"renders"| Register
    Providers -->|"renders"| CredList
    Providers -->|"renders"| Settings
    Browser -->|"encrypt/decrypt data"| Crypto
    Browser -->|"generate/validate TOTP"| TOTPMod

    Login -->|"authenticate"| Auth
    Auth -->|"issue session"| Login
    OTP -->|"OTP auth"| Auth
    TOTPPage -->|"TOTP verify"| Auth

    Root -->|"fetch encrypted vault"| Database
    CredList -->|"save encrypted record"| Database
    NewCred -->|"save encrypted record"| Database
    Database -->|"return encrypted blob"| Root
    Database -->|"return encrypted blob"| CredList
    Pages -->|"upload/download assets"| Storage

    Providers --> AppwriteClient
    Providers --> Utils

    %% Click Events
    click Providers "https://github.com/whisperrnote/auth/blob/main/app/providers.tsx"
    click Root "https://github.com/whisperrnote/auth/blob/main/app/page.tsx"
    click Login "https://github.com/whisperrnote/auth/blob/main/app/login/page.tsx"
    click OTP "https://github.com/whisperrnote/auth/blob/main/app/login/otp/page.tsx"
    click Register "https://github.com/whisperrnote/auth/blob/main/app/register/page.tsx"
    click Forgot "https://github.com/whisperrnote/auth/blob/main/app/forgot-password/page.tsx"
    click Reset "https://github.com/whisperrnote/auth/blob/main/app/reset-password/page.tsx"
    click CredList "https://github.com/whisperrnote/auth/blob/main/app/credentials/page.tsx"
    click NewCred "https://github.com/whisperrnote/auth/blob/main/app/credentials/new/page.tsx"
    click Folders "https://github.com/whisperrnote/auth/blob/main/app/folders/page.tsx"
    click Settings "https://github.com/whisperrnote/auth/blob/main/app/settings/page.tsx"
    click TOTPPage "https://github.com/whisperrnote/auth/blob/main/app/totp/page.tsx"
    click AppShell "https://github.com/whisperrnote/auth/blob/main/components/layout/AppShell.tsx"
    click Header "https://github.com/whisperrnote/auth/blob/main/components/layout/Header.tsx"
    click Button "https://github.com/whisperrnote/auth/blob/main/components/ui/Button.tsx"
    click Card "https://github.com/whisperrnote/auth/blob/main/components/ui/Card.tsx"
    click Dropdown "https://github.com/whisperrnote/auth/blob/main/components/ui/DropdownMenu.tsx"
    click Input "https://github.com/whisperrnote/auth/blob/main/components/ui/Input.tsx"
    click AppwriteClient "https://github.com/whisperrnote/auth/blob/main/lib/appwrite.ts"
    click Utils "https://github.com/whisperrnote/auth/blob/main/lib/utils.ts"
    click Static "https://github.com/whisperrnote/auth/tree/main/public/"
    click Env "https://github.com/whisperrnote/auth/blob/main/env.sample"
    click NextConfig "https://github.com/whisperrnote/auth/blob/main/next.config.ts"
    click Globals "https://github.com/whisperrnote/auth/blob/main/app/globals.css"

    %% Styles
    classDef client fill:#cfe2ff,stroke:#1c7ed6,color:#1c7ed6
    classDef frontend fill:#e3fafc,stroke:#12b886,color:#087f5b
    classDef backend fill:#d3f9d8,stroke:#37b24d,color:#2b8a3e
    classDef db fill:#f1f3f5,stroke:#868e96,color:#495057
    classDef crypto fill:#fff4e6,stroke:#f08c00,color:#d9480f
    classDef component fill:#f8f0fc,stroke:#845ef7,color:#5f3dc4
    classDef config fill:#f1f3f5,stroke:#adb5bd,color:#495057
```
