# sameerchn/document-verification-audit-log-system architecture

> Architecture diagram of the GitHub repository sameerchn/document-verification-audit-log-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sameerchn/document-verification-audit-log-system
- Repository: https://github.com/sameerchn/document-verification-audit-log-system

## Overview

##### What this project is (type + purpose)

From the file tree and README, this is a **production-deployed Next.js (TypeScript/Node.js) web application** running on an **Azure VM** inside a **Docker container**, fronted by **NGINX reverse proxy with Let’s Encrypt TLS**, and using **Azure Cosmos DB (MongoDB API likely)** as the database.

Functionally, the app is a **Document Verification + Audit Log system**:
- Users authenticate (register/login/logout/me endpoints)
- Users upload/manage documents (`/api/documents`)
- Documents can be verified (`/api/verify`)
- Actions are recorded and retrievable as audit logs (`/api/audit-logs`)

- **Infrastructure / deployment topology** (VM, NGINX, Docker, TLS, DDNS, firewall ports)
- **Application architecture** (Next.js UI, API routes, auth middleware, DB, storage/crypto utilities)

##### Top-level signals
- `app/` with `app/api/.../route.ts` ⇒ **Next.js App Router** with **server-side API routes**
- `components/` and `components/ui/` ⇒ React UI layer + shared UI kit (shadcn-like)
- `lib/` ⇒ server-side utilities and integrations:
- `lib/mongodb.ts` ⇒ Cosmos DB connectivity via Mongo-style driver
- `lib/auth.ts`, `lib/auth-middleware.ts` ⇒ auth/session enforcement for API routes
- `lib/crypto-utils.ts` ⇒ hashing/signing/verification primitives (likely used by verify flow)
- `lib/types.ts` ⇒ shared domain types
- `Dockerfile` ⇒ containerized runtime for the app
- `.github/workflows/main.yml` ⇒ CI/CD pipeline presence
- `next.config.mjs`, `postcss.config.mjs` ⇒ Next.js + styling toolchain
- `.example.env` ⇒ environment-driven configuration (DB conn string, secrets, etc.)

##### API surface (directly diagrammable)
Under `app/api`:
- `auth/register`, `auth/login`, `auth/logout`, `auth/me`
- `documents` and `documents/[id]`
- `verify`
- `audit-logs`

##### System Context (who uses it + external dependencies)
Include:
- **User / Browser**
- **Domain (DDNS provider)** as a dependency mapping domain → static IP
- **Azure VM** (system boundary)
- **Cosmos DB** (external managed service)
Optionally:

- Browser → System over HTTPS
- System → Cosmos DB over outbound connection
- Operator → VM over SSH

##### Container / Deployment Topology (what runs where)

**Browser**
→ **Internet/DNS (DDNS domain)**
→ **Azure VM (Ubuntu 22.04, Static Public IP)**
→ **NGINX (Reverse Proxy + SSL termination + HTTP→HTTPS redirect)**
→ **Docker container (private network)**
→ **Next.js Node server (listening on localhost:3000 inside VM via docker port mapping)**
→ **Azure Cosmos DB (firewall allows VM public IP)**

Also annotate:
- Inbound ports open on VM: **22 / 80 / 443**
- TLS cert issuance/renewal: **Certbot/Let’s Encrypt** (on VM, interacting with NGINX)

- **UI / Pages**
- `app/layout.tsx`, `app/page.tsx`
- `components/*` (DocumentUpload, DocumentVerify, DocumentList, AuditLogs, AuthForm, ThemeProvider)
- **API Routes (server)**
- Auth API: `/api/auth/*`
- Documents API: `/api/documents`, `/api/documents/[id]`
- Verify API: `/api/verify`
- Audit Logs API: `/api/audit-logs`
- **Cross-cutting server utilities**
- `lib/auth-middleware.ts` (guards protected routes)
- `lib/auth.ts` (session/token logic)
- `lib/mongodb.ts` (DB client / connection)
- `lib/storage.ts` (file persistence abstraction)
- `lib/crypto-utils.ts` (hashing/signature/verification)
- `lib/types.ts` (domain types)

- UI Components → call API Routes via HTTPS (same domain)
- API Routes → Auth middleware (for protected endpoints)
- API Routes → Cosmos DB via `lib/mongodb.ts`
- Verify route → `crypto-utils` (and likely reads document data from DB/storage)
- Documents route → `storage.ts` + DB (metadata)
- Audit-logs route → DB (audit log collection)

##### Infrastructure / edge
- **DDNS Provider** (domain → Azure Static IP)
- **Azure VM** (Ubuntu 22.04, B1s)
- **NGINX reverse proxy**
- **Let’s Encrypt + Certbot** (certificate lifecycle)
- **Docker runtime**
- **GitHub Actions** (build/deploy pipeline)

##### Application
- **Next.js App Router runtime** (single deployable)
- **React UI components** (client-side interactions)
- **API routes** grouped by domain:
- Auth
- Documents
- Verification
- Audit Logs

##### Data / state
- **Azure Cosmos DB** (with firewall rule: allow VM static IP)

##### Next.js serves
- HTML/JS/CSS for UI
- API JSON responses for `/api/...`
##### API handlers read/write
- Cosmos DB (documents, users/sessions, audit logs)
- Storage provider (document binaries) if applicable

##### Auth flow (important cross-cutting)
- UI → `/api/auth/login` / `/api/auth/register`
- Protected endpoints use `lib/auth-middleware.ts` before executing core logic
- `/api/auth/me` used by UI to determine session state

##### Audit log flow (purpose-critical)
- Documents/Verify actions → write audit entry in DB
- UI → `/api/audit-logs` to render audit trail (`components/audit-logs.tsx`)

##### Deployment flow (CI/CD readiness from README)
- Developer push → GitHub Actions
- Actions build Docker image → push to registry
- Actions SSH to VM → pull latest image → restart container

##### Architectural patterns worth highlighting (don’t hide these)

- **Reverse-proxy pattern** (NGINX in front of app container)
- **SSL termination at the edge** (NGINX + Certbot)
- **Single deployable web app** (Next.js provides UI + API in one runtime)
- **Route-based backend modularity** (each `app/api/.../route.ts` is a component boundary)
- **Cross-cutting middleware for auth** (`lib/auth-middleware.ts`)
- **Environment-based configuration** (via `.env`, see `.example.env`)
- **Network perimeter via DB firewall rules** (Cosmos DB allows VM static IP)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: System Context
%% =========================
subgraph "Diagram 1 — System Context"
direction TB

U["User (Browser)"]:::external

DDNS["DDNS Provider\nDomain → Azure Static IP"]:::edge

subgraph "System Boundary: Document Verification + Audit Log Web App"
direction TB
SYS["Web App (Next.js)\nUI + API (single deployable)"]:::runtime
end

COSMOS[("Azure Cosmos DB\n(MongoDB API)")]:::data
LE["Let's Encrypt\n(Certificate Authority)"]:::edge
OP["Admin/Operator\n(SSH)"]:::external

U -->|"HTTPS:443"| SYS
DDNS -->|"DNS A/AAAA record"| SYS
SYS -->|"MongoDB/TLS (outbound)"| COSMOS
SYS <-->|"ACME HTTP-01/HTTPS"| LE
OP -->|"SSH:22"| SYS
end

%% ===================================
%% Diagram 2: Deployment / Topology
%% ===================================
subgraph "Diagram 2 — Container / Deployment Topology (Azure VM)"
direction TB

B["Browser"]:::external
INTERNET["Internet + DNS (DDNS)"]:::edge

subgraph "Azure Subscription"
direction TB

subgraph "Azure VM (Ubuntu 22.04)\nInbound: 22, 80, 443\nStatic Public IP"
direction TB

FW["Host Firewall / NSG\nAllow: 22/80/443"]:::edge

subgraph "Edge Layer"
direction TB
NGINX["NGINX Reverse Proxy\nHTTP→HTTPS redirect\nTLS termination"]:::edge
CERTBOT["Certbot\nLet's Encrypt renewal"]:::edge
end

subgraph "Compute Layer"
direction TB
DOCKER["Docker Runtime"]:::runtime
subgraph "App Container (private network)"
direction TB
NEXT["Next.js Node Server\n(listens :3000)"]:::runtime
end
end

end

COSMOS2[("Azure Cosmos DB\nFirewall: allow VM public IP only")]:::data
end

B -->|"HTTPS:443"| INTERNET
INTERNET -->|"DNS→Static IP"| FW
FW -->|"TCP:443"| NGINX
FW -->|"TCP:80"| NGINX
FW -->|"TCP:22"| SSHD["sshd"]:::edge

NGINX -->|"HTTP:3000 (localhost)"| DOCKER
DOCKER -->|"Container port:3000"| NEXT

CERTBOT <-->|"Updates certs\nreload NGINX"| NGINX

NEXT -->|"MongoDB/TLS (outbound)"| COSMOS2
end

%% ===================================
%% Diagram 3: Application Components
%% ===================================
subgraph "Diagram 3 — Next.js Application Components (App Router)"
direction TB

subgraph "UI Layer (React)"
direction TB
ROOT["App Root / Pages\nlayout + home + globals"]:::frontend
FEAT["Feature Components"]:::frontend
UIKIT["Shared UI Kit\n(components/ui)"]:::frontend
HOOKS["Client Hooks\n(use-mobile, use-toast)"]:::frontend
end

subgraph "Server Layer (Next.js API Routes)"
direction TB
subgraph "Auth API"
direction TB
AUTHR["POST /api/auth/register"]:::api
AUTHL["POST /api/auth/login"]:::api
AUTHO["POST /api/auth/logout"]:::api
AUTHM["GET /api/auth/me"]:::api
end

subgraph "Documents API"
direction TB
DOCS["/api/documents\n(list/create)"]:::api
DOCID["/api/documents/[id]\n(read/update/delete)"]:::api
end

subgraph "Verification API"
direction TB
VERIFY["POST /api/verify"]:::api
end

subgraph "Audit Logs API"
direction TB
AUDIT["GET /api/audit-logs"]:::api
end
end

subgraph "Cross-cutting Libraries (lib/)"
direction TB
AUTHLIB["Auth / Session Logic"]:::lib
AUTHMW["Auth Middleware / Route Guard"]:::lib
MDB["Cosmos DB (Mongo) Connector"]:::lib
CRYPTO["Crypto Utilities\n(hashing/signing/verify)"]:::lib
STORE["Document Storage Abstraction"]:::lib
TYPES["Shared Domain Types"]:::lib
end

subgraph "Data Services"
direction TB
DB[("Cosmos DB\n(users/sessions, documents, auditLogs)")]:::data
STORAGE[("Storage Provider\n(document binaries)")]:::data
end

subgraph "Config & Build"
direction TB
ENV["Environment Variables\n(.env based)"]:::config
BUILD["Next.js / Tooling Config\nnext/postcss/tsconfig/package"]:::config
end

%% UI -> API
ROOT -->|"fetch /api/* (same origin)"| AUTHL
ROOT -->|"fetch /api/*"| DOCS
FEAT -->|"calls"| VERIFY
FEAT -->|"calls"| AUDIT
FEAT -->|"uses"| UIKIT
FEAT -->|"uses"| HOOKS

%% API -> middleware/libs
DOCS -->|"guardedBy"| AUTHMW
DOCID -->|"guardedBy"| AUTHMW
VERIFY -->|"guardedBy"| AUTHMW
AUDIT -->|"guardedBy"| AUTHMW
AUTHM -->|"uses"| AUTHLIB
AUTHL -->|"uses"| AUTHLIB
AUTHR -->|"uses"| AUTHLIB
AUTHO -->|"uses"| AUTHLIB

%% API -> data access
AUTHLIB -->|"reads/writes"| MDB
DOCS -->|"uses"| MDB
DOCID -->|"uses"| MDB
AUDIT -->|"uses"| MDB
VERIFY -->|"uses"| MDB

%% documents + verify -> storage/crypto
DOCS -->|"storeBinary"| STORE
DOCID -->|"getBinary"| STORE
VERIFY -->|"hash/verify"| CRYPTO
VERIFY -->|"readBinary"| STORE

%% libs -> services
MDB -->|"connect"| DB
STORE -->|"persist"| STORAGE

%% types shared
ROOT -->|"types"| TYPES
DOCS -->|"types"| TYPES
VERIFY -->|"types"| TYPES
AUDIT -->|"types"| TYPES

%% config consumed
ENV -->|"configures"| AUTHLIB
ENV -->|"configures"| MDB
ENV -->|"configures"| STORE
BUILD -->|"builds"| ROOT
BUILD -->|"builds"| AUTHL
end

%% =========================
%% CI/CD Pipeline (separate lane)
%% =========================
subgraph "CI/CD — Build & Deploy Pipeline"
direction TB
DEV["Developer Push"]:::external
GHA["GitHub Actions\nCI/CD Workflow"]:::cicd
REG["Container Registry"]:::cicd
VMDEP["Azure VM Deployment\n(SSH pull + restart container)"]:::cicd

DEV -->|"git push"| GHA
GHA -->|"build Docker image"| REG
GHA -->|"SSH deploy"| VMDEP
VMDEP -->|"docker pull/run"| DOCKER
end

%% =========================
%% Click Events (component_mapping)
%% =========================
click ROOT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/layout.tsx"
click ROOT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/page.tsx"
click ROOT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/globals.css"

click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/audit-logs.tsx"
click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/auth-form.tsx"
click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/document-list.tsx"
click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/document-upload.tsx"
click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/document-verify.tsx"
click FEAT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/components/theme-provider.tsx"

click UIKIT "https://github.com/sameerchn/document-verification-audit-log-system/tree/main/components/ui/"

click AUTHR "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/auth/register/route.ts"
click AUTHL "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/auth/login/route.ts"
click AUTHO "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/auth/logout/route.ts"
click AUTHM "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/auth/me/route.ts"

click DOCS "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/documents/route.ts"
click DOCID "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/documents/[id]/route.ts"
click VERIFY "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/verify/route.ts"
click AUDIT "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/app/api/audit-logs/route.ts"

click AUTHLIB "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/auth.ts"
click AUTHMW "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/auth-middleware.ts"
click MDB "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/mongodb.ts"
click CRYPTO "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/crypto-utils.ts"
click STORE "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/storage.ts"
click TYPES "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/lib/types.ts"

click ENV "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/.example.env"
click DOCKER "https://github.com/sameerchn/document-verification-audit-log-system/tree/main/Dockerfile"
click GHA "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/.github/workflows/main.yml"

click BUILD "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/next.config.mjs"
click BUILD "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/postcss.config.mjs"
click BUILD "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/tsconfig.json"
click BUILD "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/package.json"

click HOOKS "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/hooks/use-mobile.ts"
click HOOKS "https://github.com/sameerchn/document-verification-audit-log-system/blob/main/hooks/use-toast.ts"

%% =========================
%% Styles (color-coded)
%% =========================
classDef external fill:#ffffff,stroke:#111827,stroke-width:1.5px,color:#111827
classDef edge fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e
classDef runtime fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef frontend fill:#fce7f3,stroke:#db2777,stroke-width:1.5px,color:#831843
classDef api fill:#ffedd5,stroke:#f97316,stroke-width:1.5px,color:#7c2d12
classDef lib fill:#ede9fe,stroke:#7c3aed,stroke-width:1.5px,color:#3b0764
classDef data fill:#fef9c3,stroke:#ca8a04,stroke-width:1.5px,color:#713f12
classDef config fill:#f3f4f6,stroke:#6b7280,stroke-width:1.5px,color:#111827
classDef cicd fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
```
