How sameerchn/document-verification-audit-log-system works
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)