# didit-protocol/didit-full-demo architecture

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

- Interactive diagram: https://gitdiagram.com/didit-protocol/didit-full-demo
- Repository: https://github.com/didit-protocol/didit-full-demo

## Overview

##### Project type and purpose
- This is a full‑stack Next.js application (“didit‑full‑demo”) showcasing a vanilla implementation of the Didit Identity Verification flow.
- It combines a React‑based frontend (Next.js App Router + UI components), backend API routes (NextAuth for auth, custom registration and verification endpoints), a database (Prisma + SQLite by default), and integration with the external Didit identity service (via REST and webhooks).

##### File structure
- Top‑level config & scripts:
- next.config.mjs, tsconfig.json, postcss.config.mjs, tailwind.config.ts
- .env.example for environment variables (CLIENT_ID, CLIENT_SECRET, SHARED_SECRET_KEY, WEBHOOK_URL)
- Prisma folder: schema.prisma defines User and VerificationSession models
- src/app: contains Next.js pages and API route handlers under /api
- /api/auth/[...nextauth]/route.ts – NextAuth authentication with Didit OAuth provider
- /api/register/route.ts – user registration
- /api/verification/route.ts – starts a new verification session
- /api/verification/webhook/route.ts – receives Didit webhook callbacks
- client‑rendered pages: /signin, /register, /callback, plus root layout and global CSS
- src/components & src/components/ui: reusable React UI primitives (buttons, forms, dialogs)
- src/lib: business logic and integrations
- auth.ts – session checks, protected‑route logic
- diditAuth.ts – HTTP client / helper to call Didit API
- prisma.ts – Prisma client instantiation
- utils.ts – misc utilities
- src/middleware.ts – route protection, e.g. guard pages requiring auth
- src/types – TypeScript type augmentations (NextAuth, custom types)

##### README for additional insights
- Describes environment setup, Prisma models, and the verification flow:
1. User signs up → User record (`isVerified=false`)
2. App creates a VerificationSession (`status = NOT_STARTED`)
3. Frontend redirects user to Didit hosted workflow
4. Didit calls back via webhook to update VerificationSession.status
5. On “Approved,” app sets User.isVerified = true
- Shows how Prisma migrations and client generation are used

a. Frontend (React/Next.js App Router pages & UI components)
b. Backend (Next.js API routes + business logic in src/lib)
c. Database (Prisma Client + underlying SQLite or production database)
d. NextAuth Authentication Layer (OAuth handshake + session store)
e. External Didit Service (REST API calls to initiate verification + webhooks for status updates)
f. Webhook Tunnel (e.g., ngrok in dev)

##### Relationships and interactions
- User’s browser ↔ Next.js SSR/CSR pages
- Browser → POST /api/register → Backend creates User in DB
- Browser → POST /api/verification → Backend creates VerificationSession in DB & obtains Didit workflow URL
- Browser → Didit hosted pages (external domain)
- Didit → webhook → POST /api/verification/webhook → Backend updates VerificationSession status and, on success, sets User.isVerified
- NextAuth handlers under /api/auth handle login, session cookies, JWT storage (DB relations via Prisma)
- Any authenticated page uses middleware.ts and auth.ts logic to guard content

##### Architectural patterns and design principles
- Monolithic repository but modularized into clear “layers”: presentation (components + pages), API (route handlers), data (Prisma ORM), external integration (DiditAuth), and cross‑cutting concerns (auth, middleware, utilities).
- Next.js App Router pattern: file‑based routing for pages & API.
- MVC‑lite: route handlers act as controllers talking to the model (Prisma) and rendering views (JSON or next pages).
- Event‑driven update via webhooks for asynchronous verification updates.

##### Technologies, frameworks, and libraries to annotate
- Next.js 13 (App Router) + React + TypeScript
- NextAuth.js for OAuth and session management
- Prisma ORM + SQLite (dev) or Postgres/MySQL in production
- Tailwind CSS for styling
- Didit Identity Verification external API + webhooks
- ngrok (or equivalent) for local webhook tunneling

##### Detailed checklist
- Each major folder (src/app, src/api, src/lib, prisma) corresponds to a component or layer
- NextAuth as a subcomponent of API with its own data store relations (sessions, accounts)
- Middleware.ts as a gating mechanism between Frontend pages and API endpoints (authentication guard)
- If desired, annotate the UI component library as a shared resource under Frontend

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Home["Home Page<br/>(src/app/page.tsx)"]:::frontend
        Layout["Layout<br/>(src/app/layout.tsx)"]:::frontend
        Globals["Global CSS<br/>(src/app/globals.css)"]:::frontend
        RegisterPage["Register Page<br/>(src/app/register/page.tsx)"]:::frontend
        SignInPage["Sign-In Page<br/>(src/app/signin/page.tsx)"]:::frontend
        CallbackPage["Callback Page<br/>(src/app/callback/page.tsx)"]:::frontend
        subgraph "UI Components Library"
            direction TB
            SignInComp["Sign-In Component<br/>(src/components/sign-in.tsx)"]:::frontend
            ButtonUI["Button UI<br/>(src/components/ui/button.tsx)"]:::frontend
            InputUI["Input UI<br/>(src/components/ui/input.tsx)"]:::frontend
            LabelUI["Label UI<br/>(src/components/ui/label.tsx)"]:::frontend
            DialogUI["Dialog UI<br/>(src/components/ui/dialog.tsx)"]:::frontend
            CardUI["Card UI<br/>(src/components/ui/card.tsx)"]:::frontend
            AlertUI["Alert UI<br/>(src/components/ui/alert.tsx)"]:::frontend
            BadgeUI["Badge UI<br/>(src/components/ui/badge.tsx)"]:::frontend
            ScrollAreaUI["Scroll Area UI<br/>(src/components/ui/scroll-area.tsx)"]:::frontend
            SkeletonUI["Skeleton UI<br/>(src/components/ui/skeleton.tsx)"]:::frontend
            SwitchUI["Switch UI<br/>(src/components/ui/switch.tsx)"]:::frontend
            TabsUI["Tabs UI<br/>(src/components/ui/tabs.tsx)"]:::frontend
            TooltipUI["Tooltip UI<br/>(src/components/ui/tooltip.tsx)"]:::frontend
        end
    end

    %% Backend/API Layer
    subgraph "Backend / API" 
        direction TB
        Middleware["Middleware Guard<br/>(src/middleware.ts)"]:::backend
        subgraph "API Routes"
            direction TB
            AuthAPI["NextAuth Auth Route<br/>(src/app/api/auth/[...nextauth]/route.ts)"]:::backend
            RegisterAPI["Register API<br/>(src/app/api/register/route.ts)"]:::backend
            VerificationAPI["Verification API<br/>(src/app/api/verification/route.ts)"]:::backend
            WebhookAPI["Webhook Receiver<br/>(src/app/api/verification/webhook/route.ts)"]:::backend
        end
        subgraph "Business Logic & Integration"
            direction TB
            AuthLib["Auth Logic<br/>(src/lib/auth.ts)"]:::backend
            NextAuthTypes["NextAuth Types<br/>(src/types/next-auth.d.ts)"]:::backend
            DiditAuth["Didit Auth Client<br/>(src/lib/diditAuth.ts)"]:::backend
            Utils["Utilities<br/>(src/lib/utils.ts)"]:::backend
        end
    end

    %% Database Layer
    subgraph "Database / ORM"
        direction TB
        PrismaClient["Prisma Client<br/>(src/lib/prisma.ts)"]:::database
        Schema["Prisma Schema<br/>(prisma/schema.prisma)"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DiditService["Didit API Service"]:::external
        WebhookTunnel["Webhook Tunnel (ngrok)"]:::external
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        Env["Env Variables<br/>(.env.example)"]:::config
        NextConfig["Next Config<br/>(next.config.mjs)"]:::config
        TSConfig["TS Config<br/>(tsconfig.json)"]:::config
        TailwindConfig["Tailwind Config<br/>(tailwind.config.ts)"]:::config
        PostCSS["PostCSS Config<br/>(postcss.config.mjs)"]:::config
    end

    %% Connections
    %% Frontend to UI
    Home --> SignInComp
    RegisterPage --> InputUI
    RegisterPage --> ButtonUI
    RegisterPage --> LabelUI

    SignInPage --> SignInComp
    CallbackPage --> ButtonUI

    %% Frontend to Middleware/API
    Home --> Middleware
    RegisterPage --> Middleware
    SignInPage --> Middleware
    CallbackPage --> Middleware

    Middleware --> AuthAPI
    RegisterPage --> RegisterAPI
    RegisterPage --> VerificationAPI
    SignInPage --> AuthAPI

    %% API to Business Logic & Config
    AuthAPI --> AuthLib
    AuthAPI --> NextAuthTypes
    AuthAPI --> PrismaClient
    RegisterAPI --> PrismaClient
    VerificationAPI --> PrismaClient
    VerificationAPI --> DiditAuth
    WebhookAPI --> DiditAuth
    WebhookAPI --> PrismaClient

    AuthAPI --> Env
    RegisterAPI --> Env
    VerificationAPI --> Env
    WebhookAPI --> Env
    DiditAuth --> Env

    %% API to Database
    PrismaClient --> Schema

    %% Verification flow to external
    VerificationAPI -->|"POST to Didit REST"| DiditService
    DiditService -->|"workflow URL"| CallbackPage
    DiditService -->|"Webhook callback"| WebhookTunnel
    WebhookTunnel --> WebhookAPI

    %% Style classes
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24;

    %% Click Events - Frontend Pages
    click Home "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/page.tsx"
    click Layout "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/layout.tsx"
    click Globals "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/globals.css"
    click RegisterPage "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/register/page.tsx"
    click SignInPage "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/signin/page.tsx"
    click CallbackPage "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/callback/page.tsx"

    %% Click Events - UI Components
    click SignInComp "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/sign-in.tsx"
    click ButtonUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/button.tsx"
    click InputUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/input.tsx"
    click LabelUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/label.tsx"
    click DialogUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/dialog.tsx"
    click CardUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/card.tsx"
    click AlertUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/alert.tsx"
    click BadgeUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/badge.tsx"
    click ScrollAreaUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/scroll-area.tsx"
    click SkeletonUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/skeleton.tsx"
    click SwitchUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/switch.tsx"
    click TabsUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/tabs.tsx"
    click TooltipUI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/components/ui/tooltip.tsx"

    %% Click Events - Backend API Routes
    click AuthAPI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/api/auth/[...nextauth]/route.ts"
    click RegisterAPI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/api/register/route.ts"
    click VerificationAPI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/api/verification/route.ts"
    click WebhookAPI "https://github.com/didit-protocol/didit-full-demo/blob/main/src/app/api/verification/webhook/route.ts"

    %% Click Events - Auth Layer
    click AuthLib "https://github.com/didit-protocol/didit-full-demo/blob/main/src/lib/auth.ts"
    click NextAuthTypes "https://github.com/didit-protocol/didit-full-demo/blob/main/src/types/next-auth.d.ts"

    %% Click Events - Business Logic
    click DiditAuth "https://github.com/didit-protocol/didit-full-demo/blob/main/src/lib/diditAuth.ts"
    click Utils "https://github.com/didit-protocol/didit-full-demo/blob/main/src/lib/utils.ts"

    %% Click Events - Database & ORM
    click PrismaClient "https://github.com/didit-protocol/didit-full-demo/blob/main/src/lib/prisma.ts"
    click Schema "https://github.com/didit-protocol/didit-full-demo/blob/main/prisma/schema.prisma"

    %% Click Events - Middleware
    click Middleware "https://github.com/didit-protocol/didit-full-demo/blob/main/src/middleware.ts"

    %% Click Events - Configuration
    click Env "https://github.com/didit-protocol/didit-full-demo/blob/main/.env.example"
    click NextConfig "https://github.com/didit-protocol/didit-full-demo/blob/main/next.config.mjs"
    click TSConfig "https://github.com/didit-protocol/didit-full-demo/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/didit-protocol/didit-full-demo/blob/main/tailwind.config.ts"
    click PostCSS "https://github.com/didit-protocol/didit-full-demo/blob/main/postcss.config.mjs"
```
