firmflow. — Detailed Technical Architecture¶

Version: 1.2.0 | Last Updated: February 2026

Table of Contents¶

System Overview
Technology Stack
Deployment Architecture
Application Layer Architecture
Database Architecture
Authentication & Security Architecture
AI Engine Architecture
Storage Architecture
API Surface Map
Licensing System Architecture
Email & Notification Architecture
Payments Architecture
Audit & Compliance Architecture
Multi-Tenancy Architecture
Frontend Component Architecture
Key Workflows
Environment & Configuration
Observability & Monitoring
Data Flow Diagrams

1. System Overview¶

firmflow. is a multi-tenant, on-premise-first document management and tax compliance platform purpose-built for Nigerian accounting and professional services firms. It is designed to operate entirely within a firm's own infrastructure (on-premise or self-hosted cloud VM), with an optional secure outbound-only hybrid AI bridge for intelligent processing.

Design Principles¶

Principle	Implementation
Data Sovereignty	All documents stored on-premise; client data never leaves the licensed server
Multi-Tenancy	Every database row is scoped to a `firmId`; no cross-firm data leakage possible
Hybrid AI	AI runs via an outbound-only bridge; only anonymized metadata sent to Google
Immutable Audit Trail	Cryptographically chained SHA-256 audit log resistant to tampering
License-Gated	HMAC-signed license keys control access, edition features, and seat limits
Nigerian Compliance	FIRS, LIRS, SCUML, NDPA, CAC, ICAN, ANAN standards embedded throughout

2. Technology Stack¶

Runtime & Framework¶

Layer	Technology	Version	Rationale
Framework	Next.js	15.x	App Router; SSR + API routes in a single deployable unit
Runtime	Node.js	20 LTS	Required for `fs`, `crypto`, `bcryptjs` (no Edge Runtime)
Language	TypeScript	5.x	Strict mode; zero implicit `any`
Package Manager	npm	10.x	Lock file committed

Frontend¶

Layer	Technology	Notes
UI Library	React 18	Server Components + Client Components mixed model
Styling	Tailwind CSS 4	Utility-first; no CSS-in-JS runtime
Component Kit	shadcn/ui	Radix UI primitives; fully owned source, no vendor lock
Icons	lucide-react	Tree-shaken SVG icons
State	React `useState`/`useEffect`	No global state library; server-first mindset
Auth Client	next-auth/react	`useSession`, `signOut`
Fonts	Inter (System Fallback)	Loaded via `next/font`

Backend & Data¶

Layer	Technology	Notes
ORM	Prisma	v5.22 — schema-first, type-safe queries
Database	PostgreSQL	Neon (cloud) or self-hosted; any Postgres 14+
Auth	Auth.js v5 (NextAuth)	Credentials + LDAP + MFA; DB sessions via Prisma adapter
File Storage	Local FS / S3 / NAS	Pluggable via `StorageDriver` interface
Encryption	AES-256-GCM	All stored files encrypted at rest on any driver
Email	Resend	Transactional emails; console fallback in dev
Payments	Paystack	Nigerian market; Kobo-denominated transactions
Push Notifications	Firebase Cloud Messaging (FCM)	Mobile push to client portal users

AI Engine¶

Component	Technology	Notes
Orchestration	Genkit	Google's AI flow orchestration framework
Model	Gemini 2.5 Flash	`googleai/gemini-2.5-flash` — fastest, cheapest Gemini model
Schemas	Zod	Input/output schema validation for all AI flows

Infrastructure¶

Component	Technology	Notes
Containerisation	Docker	Multi-stage build (`node:20-alpine`); standalone Next.js output
Orchestration	Docker Compose	Full stack: app + Postgres + volume mounts
CI	GitHub Actions	TypeCheck → Lint → Test → Build on every PR
Monitoring	Instrumentation hook	Sentry DSN stub; env validation on startup

3. Deployment Architecture¶

┌─────────────────────────────────────────────────────────────────────────┐
│                         On-Premise Deployment                           │
│                                                                         │
│  ┌──────────────┐   ┌──────────────────────────────────────────────┐   │
│  │              │   │          Docker Host (firm server)            │   │
│  │   Reverse    │   │                                              │   │
│  │   Proxy      │──▶│  ┌─────────────┐    ┌───────────────────┐   │   │
│  │  (Nginx /    │   │  │  Next.js    │    │   PostgreSQL 14+  │   │   │
│  │   Caddy)     │   │  │  App        │◀──▶│   (Local or NAS)  │   │   │
│  │  TLS 1.3     │   │  │  Port 9002  │    └───────────────────┘   │   │
│  │              │   │  │             │                             │   │
│  └──────────────┘   │  │             │    ┌───────────────────┐   │   │
│                     │  │  (Standalone│    │   Local FS / NAS  │   │   │
│                     │  │   bundle)   │◀──▶│   Encrypted Vault │   │   │
│                     │  └─────────────┘    └───────────────────┘   │   │
│                     └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │ Outbound-only
                              TLS 1.3 / HTTPS
                                    ▼
                    ┌───────────────────────────────┐
                    │   Google AI API (Gemini)       │
                    │   (metadata only — no docs)    │
                    └───────────────────────────────┘
                    ┌───────────────────────────────┐
                    │   Resend Email API             │
                    └───────────────────────────────┘
                    ┌───────────────────────────────┐
                    │   Paystack Payments API        │
                    └───────────────────────────────┘

Deployment Config (`next.config.ts`)¶

Output: standalone — ships only the minimal Node.js bundle needed to run; no node_modules bloat
Security headers applied globally at the Next.js layer: X-Frame-Options: DENY, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Content-Security-Policy
CORS restricted to NEXT_PUBLIC_APP_URL on all /api/* routes (no wildcard)

4. Application Layer Architecture¶

src/
├── app/                         ← Next.js App Router
│   ├── (auth)/                  ← Unauthenticated routes (login, register)
│   ├── dashboard/               ← Protected staff application shell
│   │   ├── ai/                  ← AI Decision Lab
│   │   ├── audit-logs/          ← Immutable audit viewer
│   │   ├── clients/             ← Client management + onboarding wizard
│   │   ├── compliance/          ← FIRS/LIRS compliance calendar
│   │   ├── documents/           ← Document vault
│   │   ├── financials/          ← Billing & revenue
│   │   ├── requests/            ← Document request management
│   │   ├── resources/           ← Knowledge resource library
│   │   ├── settings/            ← Firm/user settings
│   │   ├── signatures/          ← e-Signature management
│   │   └── tax-prep/            ← Tax prep pipeline (Kanban)
│   ├── portal/                  ← Client portal (external-facing)
│   ├── api/                     ← REST API routes (22 namespaces)
│   └── page.tsx                 ← Marketing/landing page
│
├── ai/
│   ├── genkit.ts                ← Singleton Genkit AI client
│   └── flows/                   ← 14 named AI flows
│
├── components/
│   ├── dashboard/               ← Staff app UI components
│   ├── portal/                  ← Client portal components
│   ├── pricing/                 ← Marketing page sections
│   ├── features/                ← Feature highlight components
│   └── ui/                      ← shadcn/ui primitives
│
├── lib/                         ← Server-side utilities (20 modules)
├── hooks/                       ← React custom hooks
├── types/                       ← Global TypeScript types
├── middleware.ts                ← Edge auth guard + rate limiter + security headers
└── instrumentation.ts           ← Server startup validation

Request Lifecycle¶

Browser Request
      │
      ▼
Next.js Middleware (middleware.ts)
  ├── Rate limit check (in-memory Map, per IP)
  ├── Public route allow-list check
  ├── JWT session verification (auth())
  ├── MFA enforcement gate
  ├── Device-binding fingerprint check
  ├── Role-based route guard (CLIENT → /portal, ADMIN → /dashboard/settings)
  └── Security header injection
      │
      ▼
Next.js App Router
  ├── Server Components (data fetching at render time)
  ├── Client Components ('use client' — interactivity only)
  └── Route Handlers (API — JSON responses)
      │
      ▼
Business Logic Layer (lib/)
  ├── prisma.ts → PostgreSQL
  ├── storage.ts → File I/O
  ├── auth.ts → Identity
  └── ...

5. Database Architecture¶

Engine¶

PostgreSQL 14+ via Prisma ORM. Hosted on Neon in the cloud variant; any Postgres instance for on-premise.

Tenancy Model¶

firmId column-level isolation. Every model (except superAdmin-only) includes a firmId FK that Prisma enforces at the ORM layer. There are no row-level security policies at the DB level — isolation is 100% application-enforced via queries always scoped with where: { firmId }.

Full Entity Relationship Map¶

Firm ──┬── User (staff)
       │     └── Account (OAuth sessions)
       │     └── Session
       │     └── AuditLog entries
       │     └── AIRequestLog entries
       │
       ├── Client ──┬── Document
       │            ├── DocumentRequest → DocumentRequestItem
       │            ├── ComplianceTask → ComplianceTaskItem
       │            ├── SignatureRequest → SignatureRequestRecipient
       │            │                    └── SignatureField
       │            │                    └── SignatureEvent
       │            ├── RiskProfile (AI-generated)
       │            ├── ClientOnboarding (4-step workflow)
       │            └── TaxPrepJob (tax prep pipeline)
       │
       ├── Document ──┬── DocumentAnalysis (AI results)
       │              ├── ShareLink (expiring access)
       │              └── DocumentApproval
       │
       ├── KnowledgeResource
       ├── EngagementTemplate (ICAN letter templates)
       ├── Integration (3rd-party software connectors)
       ├── Notification
       ├── License (HMAC-signed, edition-gated)
       ├── Lead (marketing CRM)
       └── SyncNode → SyncChange (multi-branch sync)

Schema Design Decisions¶

Decision	Rationale
`BigInt` for `sizeBytes`	Files can exceed `Int` max (2.1 GB); JS handles BigInt via Prisma serialization
`Json?` for `metadata`, `settings`, `extractedData`	Avoids rigid schema for evolving AI outputs and user preferences
`@db.Text` for large strings	Prevents 255-char truncation in Postgres for notes, HTML bodies, base64 signatures
`@unique` + `cuid()` for IDs	Collision-free, URL-safe, no sequential guessing
Chained hash on `AuditLog`	`hash` + `previousHash` fields form a private Merkle-like chain
`@index` on `firmId, createdAt`	Supports the dominant query pattern: fetch-by-firm ordered by time

Key Enums¶

UserRole: SUPER_ADMIN, FIRM_ADMIN, PARTNER, STAFF, CLIENT
ComplianceCategory: FIRS_CIT, FIRS_VAT, FIRS_WHT, LIRS_PAYE, LIRS_BIS, OTHER
TaxPrepType: 9 Nigerian tax types (CIT, VAT, WHT, CGT, EDT, Stamp Duty, PAYE, BIT, Personal)
TaxPrepStage: GATHERING → REVIEW → PREPARATION → PARTNER_REVIEW → CLIENT_APPROVAL → FILING → ARCHIVED
OnboardingStepStatus: PENDING, IN_PROGRESS, COMPLETE, SKIPPED
IntegrationProvider: 12 providers including Tally (popular in Nigerian SME segment)
LicenseEdition: TRIAL, BASIC, PROFESSIONAL, ENTERPRISE
SignatureDocumentType: TAX_DOCUMENT, ENGAGEMENT_LETTER, LEGAL_DOCUMENT, CONTRACT, AGREEMENT, OTHER

6. Authentication and Security Architecture¶

Authentication Flow¶

User submits credentials
        │
        ▼
NextAuth Credentials Provider
        │
        ├── Zod schema validation (email format, min 8-char password)
        │
        ├── [If LDAP_ENABLED=true]
        │     └── LDAP bind against Active Directory (ldap.ts)
        │           ├── Success → passwordValid = true
        │           └── Failure → fall through to local
        │
        ├── Local bcrypt compare (bcryptjs, cost factor 12)
        │
        ├── Database lookup (isActive check)
        │
        ├── Update lastLoginAt, create AuditLog entry
        │
        ├── Generate device fingerprint: btoa(userAgent + IP)
        │
        └── Return JWT payload:
              { id, email, name, firmId, role, twoFactorEnabled, deviceId }

Multi-Factor Authentication (TOTP)¶

Library: otplib compatible TOTP
Secret generation + QR code enrollment via /api/settings/mfa
Middleware gates: if twoFactorEnabled && !mfaVerified → redirect to /login/mfa
Session flag mfaVerified set only after correct TOTP code submission

Device Binding¶

Device fingerprint = btoa(userAgent|ip) stored in JWT as deviceId
Every authenticated request: middleware recomputes fingerprint, compares with req.auth.user.deviceId
Mismatch → redirect to /login?error=SessionExpired (protects stolen JWT cookie reuse)

Rate Limiting (In-Process)¶

Implemented in middleware.ts using a Map<string, {count, resetAt}>
Auth routes: 20 requests/IP/minute
Signature/password routes: 5 requests/IP/minute
⚠️ Note: In-memory only — does not persist across Node.js instances (acceptable for single-instance on-premise deployment; Redis recommended for multi-instance)

Security Headers¶

Applied at two layers: 1. next.config.ts: Global X-Frame-Options, X-Content-Type-Options, CSP, Referrer-Policy, Permissions-Policy 2. middleware.ts: Applied per-request to all authenticated responses (duplicate-defense)

Content Security Policy¶

default-src 'self'
script-src 'self' 'unsafe-inline'        (no eval in prod)
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com
img-src 'self' blob: data: https://placehold.co
font-src 'self' data: https://fonts.gstatic.com
connect-src 'self' https://generativelanguage.googleapis.com https://fcm.googleapis.com
frame-ancestors 'none'                   (DENY in header + CSP)
upgrade-insecure-requests

RBAC Matrix¶

Resource	SUPER_ADMIN	FIRM_ADMIN	PARTNER	STAFF	CLIENT
All Firms Admin	✅	❌	❌	❌	❌
Firm Settings	✅	✅	❌	❌	❌
Team Management	✅	✅	❌	❌	❌
License Management	✅	✅	❌	❌	❌
Documents (Upload/View)	✅	✅	✅	✅	Portal only
Clients	✅	✅	✅	✅	❌
AI Features	✅	✅	✅	✅	❌
Dashboard	✅	✅	✅	✅	❌
Client Portal	❌	❌	❌	❌	✅

7. AI Engine Architecture¶

Genkit Configuration¶

// src/ai/genkit.ts
export const ai = genkit({
    plugins: [googleAI()],
    model: 'googleai/gemini-2.5-flash', // default model
});

AI Flow Inventory (14 Flows)¶

Flow	Trigger	Input	Output	Nigerian Context
`smartRequestAIDocumentGenerationFlow`	Manual	Client info + purpose	Document checklist	FIRS/LIRS filing context
`documentAnalysisAgentFlow`	POST `/api/documents/[id]/analyze`	File base64 + metadata	Summary, risks, compliance score, extracted data	Nigerian accounting standards
`checklistAutoSolverFlow`	POST `compliance/tasks/[id]/auto-solve`	Task + checklist items	Solved items, evidence notes	FIRS penalty framework
`complianceTaskChecklistFlow`	Compliance scheduler	Tax type + period	Checklist template	Nigerian tax calendar
`clientRiskAnalysisFlow`	Client risk assessment	Client profile	Risk score, risk factors	CBN/AML risk criteria
`clientEmailDraftFlow`	Manual	Client + purpose	Professional email draft	Formal Nigerian business language
`taxEngineFlow`	Tax calculation	Client data + tax type	Tax computation	FIRS tax tables 2024
`taxFilingExecutionFlow`	Filing automation	Tax data + entity	Filing instructions	FIRS e-filing guidance
`documentReviewFlow`	Document flagging	Document content	Review findings	Nigerian compliance flags
`firmExplorerFlow`	AI Decision Lab	Query	Firm analytics	Nigerian industry benchmarks
`firmPerformanceAuditFlow`	Firm audit	Firm metrics	Performance report	Nigerian accounting firm KPIs
`industryBenchmarkFlow`	AI Decision Lab	Industry + metrics	Benchmark comparison	Nigerian sector data
`portalFilingAgentFlow`	Client portal	Filing type	Filing guidance	FIRS/LIRS portal instructions
`vaultChatFlow`	Document Q&A	Document content + query	Contextual answer	—

AI Data Privacy Architecture¶

Client Document (on-premise)
        │
        ▼ [API route reads file from local storage]
Document Content
        │
        ▼ [Transform to base64 for AI input]
Gemini API Request ──────────────────────────────▶ Google Generative AI
                                                   (Metadata + content analysis)
                                                           │
                                                           ▼
                                                   AI Response (JSON)
                                                           │
        ◀──────────────────────────────────────────────────
        │
        ▼ [Store structured results in DocumentAnalysis table]
Firm's Local Database

⚠️ Important: The raw document content IS sent to Google AI in base64. The connection is TLS 1.3 encrypted. Firms using maximum NDPA compliance should review Google's data processing agreement before enabling document analysis on sensitive PHI documents.

8. Storage Architecture¶

Driver Interface¶

interface IStorageDriver {
    save(buffer: Buffer, storagePath: string): Promise<void>;
    read(storagePath: string):  Promise<Buffer>;
    readStream(storagePath: string): NodeJS.ReadableStream;
    delete(storagePath: string): Promise<void>;
}

Available Drivers¶

Driver	Config (`STORAGE_DRIVER`)	Use Case
`LocalStorageDriver`	`local` (default)	Development, small on-premise installs
`LocalStorageDriver` (NAS mount)	`nas`	Enterprise NAS; path from `STORAGE_NAS_PATH`
`S3StorageDriver`	`s3`	Cloud deployments (AWS S3 or S3-compatible)

Encryption-at-Rest¶

Algorithm: AES-256-GCM (authenticated encryption)
Key: STORAGE_ENCRYPTION_KEY (hex-encoded 32-byte key)
Format stored: [12-byte IV][16-byte auth tag][ciphertext]
If no key set: files stored unencrypted (warning logged)
Path traversal protection: safePath() validates all paths stay within basePath

File Naming Strategy¶

{firmId}/{timestamp}-{sha256_prefix_16}{extension}
Example: cm7abc123/1708512000-a3f1b9c2d4e5f678.pdf

This prevents: - Filename collisions (timestamp + hash) - Direct guessing of file paths (hash component) - Cross-firm access (firmId prefix as directory)

9. API Surface Map¶

22 API Namespaces (86+ endpoints)¶

Namespace	Routes	Auth Required	Admin Only
`/api/auth/*`	NextAuth handlers (signin, signout, session, CSRF)	No	No
`/api/health`	GET — system health check	No	No
`/api/contact`	POST — lead/demo request form	No	No
`/api/public/*`	Portal access, share link verify	No	No
`/api/clients`	CRUD clients, risk assessment	Yes	No
`/api/clients/[id]/onboarding`	GET/PATCH onboarding workflow	Yes	No
`/api/documents`	Upload, list, filter	Yes	No
`/api/documents/[id]/analyze`	GET/POST AI analysis	Yes	No
`/api/documents/[id]/view`	Stream file to browser	Yes	No
`/api/documents/[id]/download`	Bulk ZIP download	Yes	No
`/api/documents/[id]/extract`	Unzip document bundle	Yes	No
`/api/requests`	Document request CRUD	Yes	No
`/api/signatures`	e-Signature CRUD + signing flow	Yes	Partial
`/api/signatures/sign`	Public token-based signing	No	No
`/api/compliance/tasks`	Compliance task CRUD	Yes	No
`/api/compliance/tasks/[id]/auto-solve`	AI checklist solver	Yes	No
`/api/tax-prep`	Tax prep job CRUD	Yes	No
`/api/tax-prep/[id]`	Update stage, delete job	Yes	No
`/api/engagement-templates`	Letter template CRUD	Yes	Admin
`/api/integrations`	Software integration connector	Yes	Admin
`/api/resources`	Knowledge resource CRUD	Yes	Admin (write)
`/api/ai/smart-request`	SmartRequestAI™	Yes	No
`/api/ai/vault-chat`	Document Q&A	Yes	No
`/api/settings/*`	Firm & user settings	Yes	Admin (firm)
`/api/team/*`	Team invitations	Yes	Admin
`/api/user/preferences`	User preference save	Yes	No
`/api/admin/firms`	Super-admin firm management	Yes	SUPER_ADMIN
`/api/admin/leads`	Enterprise lead CRM	Yes	SUPER_ADMIN
`/api/billing`	Paystack integration	Yes	Admin
`/api/portal/*`	Client portal endpoints	Token/Session	No
`/api/sync`	Multi-branch node sync	Yes	No
`/api/audit`	Chain integrity verification	Yes	Admin

10. Licensing System Architecture¶

License Key Format¶

FF|{firmId}|{TIER}|{expiresAt}|{HMAC_SIGNATURE}

Example: FF|cm7abc123|PROFESSIONAL|2026-12-31|A3F1B9C2D4E5

Verification Flow¶

License Key provided
        │
        ▼
Parse 5 segments (prefix|firmId|tier|expiresAt|sig)
        │
        ├── firmId must match request context
        │
        ├── Recompute HMAC-SHA256 over (prefix|firmId|tier|expiresAt)
        │     using LICENSE_SECRET (env var)
        │
        ├── Constant-time comparison (timingSafeEqual) — prevents timing attacks
        │
        ├── Check expiry date
        │
        └── Return { valid: boolean, payload: LicensePayload }

Edition Feature Gates¶

Feature	TRIAL	BASIC	PROFESSIONAL	ENTERPRISE
Max Seats	3	5	25	Unlimited
SmartRequestAI™	Limited	❌	✅	✅
Advanced Audit	❌	❌	✅	✅
API Integration	❌	❌	❌	✅
Hardware Lock	❌	❌	Optional	✅

Node-Locking (Enterprise)¶

hardwareId field on License model
Hardware fingerprint computed from MAC address + CPU ID at install time
License validation checks hardwareId matches runtime machine

11. Email and Notification Architecture¶

Transactional Email (Resend)¶

Implemented in src/lib/mailer.ts. All emails are HTML-templated with plaintext fallback.

Email	Trigger	Template
Invitation	Admin invites team member	Magic link to accept-invite
Password Reset	User requests reset	Time-limited reset link (JWT)
Document Request	SmartRequestAI™ request sent to client	Branded document list
Signature Request	e-Sign sent to recipient	Unique signing link with access token
Signature Complete	All recipients signed	Completion notification
Welcome	New firm registered	Onboarding guide

Dev Mode: No API key = emails console.log-ed (no external calls in local dev)

In-App Notifications¶

Notification model in PostgreSQL (real-time polling or future WebSocket upgrade)
Types: INFO, SUCCESS, WARNING, ERROR, URGENT
Firm-scoped; optionally targeted to a specific userId

Push Notifications (FCM)¶

src/lib/fcm.ts — Firebase Cloud Messaging
fcmToken stored on Client model
Used for client portal mobile push (document request received, signature required)

12. Payments Architecture¶

Provider: Paystack (Primary — Nigerian Market)¶

All amounts in Kobo (₦1 = 100 Kobo) as required by Paystack API
Webhook signature verification using HMAC-SHA512

Payment Flows¶

License Purchase Flow:
User selects edition → POST /api/billing/initialize
        │
        ▼ initializeTransaction()
Paystack payment page (hosted)
        │
        ▼ User pays
Paystack webhook → POST /api/billing/webhook
        │
        ├── verifyWebhookSignature (HMAC-SHA512)
        ├── verifyTransaction (confirm payment)
        ├── Generate signed license key
        └── Activate license in DB

13. Audit and Compliance Architecture¶

Cryptographically Chained Audit Log¶

Every AuditLog entry in src/lib/audit.ts implements a blockchain-like hash chain:

Entry #1: { action: "user.login", previousHash: "000...000", hash: SHA256(content+prevHash) }
Entry #2: { action: "document.uploaded", previousHash: hash(Entry#1), hash: SHA256(content+prevHash) }
Entry #N: { previousHash: hash(Entry#N-1), hash: SHA256(content+prevHash) }

Tamper detection: Any modification to a historical entry breaks the chain. verifyAuditIntegrity(firmId) traverses all entries and re-computes every hash.

Audit Events Logged¶

Category	Events
Auth	`user.login`, `user.logout`, `user.mfa.enrolled`, `password.reset`
Documents	`document.uploaded`, `document.viewed`, `document.downloaded`, `document.deleted`, `document.analyzed`
Clients	`client.created`, `client.updated`, `onboarding.updated`
Compliance	`task.created`, `task.completed`, `task.auto-solved`
Signatures	`signature.sent`, `signature.signed`, `signature.declined`, `signature.completed`
Tax Prep	`taxprep.created`, `taxprep.updated`
Admin	`license.activated`, `team.member.invited`, `integration.connected`

Nigerian Regulatory Alignment¶

Regulation	Implementation
NDPA 2023	Data export (`/api/user/export`), retention policies (planned), access logs
FIRS e-Filing	Compliance categories match FIRS taxonomy; tax deadlines tracked
SCUML AML/CFT	SCUML screening step in `ClientOnboarding`
CAC Compliance	`rcNumber` stored on `Client`; CAC verification in onboarding
ICAN Standards	`isIcanCompliant` flag on `EngagementTemplate`; ICAN-specific letter categories
CBN KYC	Structured KYC step with CAC, TIN, SCUML triple-verification

14. Multi-Tenancy Architecture¶

Isolation Model: Shared Database, Shared Schema, Application-Level Isolation¶

PostgreSQL Instance
└── public schema
    ├── Firm table (one row per tenant)
    ├── User table (firmId FK, indexed)
    ├── Client table (firmId FK, indexed)
    ├── Document table (firmId FK, indexed)
    └── ... (all tables have firmId)

Why this model? - Simpler for on-premise deployment (single DB to backup and maintain) - Sufficient isolation when all queries are scoped via ORM - Easier to upgrade schema across all tenants simultaneously

Isolation guarantees: 1. All Prisma queries include where: { firmId: session.user.firmId } — enforced by pattern, not DB policy 2. Session JWT carries firmId — injected at login, cannot be forged without AUTH_SECRET 3. File storage partitioned by firmId/ directory prefix 4. SUPER_ADMIN is the only role that can query across firms (only in src/app/dashboard/admin/)

15. Frontend Component Architecture¶

Component Hierarchy¶

DashboardShell (layout.tsx)
├── Sidebar (navItems, adminItems, superAdminItems)
│   └── Role-based conditional rendering
├── Header (SmartRequestAI™ button, bell, user menu)
└── <main> ← Page content

Pages (Server Components — fetch data)
  └── Feature Components (Client Components — interactivity)

Key Client-Side Components (State-Bearing)¶

Component	State	API Calls
`TaxPrepKanban`	`jobs[]`, `loading`, `creating`	GET/POST/PATCH `/api/tax-prep`
`ClientOnboardingWizard`	`onboarding`, `client`, `notes`	GET/PATCH `/api/clients/[id]/onboarding`
`DocumentPreviewModal`	`analysis`, `isLoading`, `error`	GET/POST `/api/documents/[id]/analyze`
`DataExtractor`	`documents[]`, `loading`	GET `/api/documents`, POST `/api/documents/[id]/analyze`
`UserPreferences`	`settings`	PATCH `/api/user/preferences`
`FirmExplorer`	`results`, `query`	POST `/api/ai/...`
`ComplianceScheduler`	`taxType`, `month`, `year`	POST `/api/compliance/tasks`
`TeamSettings`	`members[]`, `inviteOpen`	POST `/api/team/invite`, PATCH `/api/team/[id]`

Data Fetching Pattern¶

Server Components: Fetch directly via Prisma (zero network hop — SSR)
Client Components: useEffect → fetch() → local useState
No SWR/React Query: Intentional — reduces bundle size; most data is loaded once per page visit

16. Key Workflows¶

Client Onboarding (Nigerian-Adapted)¶

New Client Created
      │
      ▼
Step 1: KYC & CAC Verification
  ├── CAC Registration Number confirmed (Corporate Affairs Commission)
  ├── FIRS Tax Identification Number validated
  └── SCUML AML/CFT screening completed
      │
      ▼
Step 2: Engagement Letter
  ├── Select from ICAN-compliant template library
  ├── Customise with firm/client variables
  ├── Send via e-Signature workflow
  └── Letter signed → stored in vault
      │
      ▼
Step 3: Document Collection
  ├── SmartRequestAI™ generates tailored document checklist
  ├── Client portal request created
  └── Client uploads via branded portal
      │
      ▼
Step 4: Risk Assessment (CBN AML/CFT)
  └── AI-powered client risk scoring
      │
      ▼
Step 5: Client Activated ✅

Tax Prep Job Lifecycle¶

New TaxPrepJob created (GATHERING)
      │
      ▼ [Documents collected from client]
REVIEW — AI document analysis, risk flags checked
      │
      ▼ [Staff prepares return]
PREPARATION — Tax computation (taxEngineFlow)
      │
      ▼ [Partner reviews]
PARTNER_REVIEW — Senior sign-off
      │
      ▼ [Client sees final]
CLIENT_APPROVAL — Client signature requested
      │
      ▼ [Filed with FIRS/LIRS]
FILING — Submission recorded, deadline met
      │
      ▼
ARCHIVED ✅ — Stored in compliance vault

Document Analysis Flow¶

Staff clicks "Analyze with AI" on document
      │
      ▼ [GET /api/documents/[id]/analyze]
          ├── Existing analysis? → Return cached
          └── None → prompt "Run analysis"
                  │
                  ▼ [POST /api/documents/[id]/analyze]
              Read file from storage (LocalDriver/S3/NAS)
              Decrypt buffer (AES-256-GCM)
              Convert to base64
                  │
                  ▼
              documentAnalysisAgentFlow (Gemini 2.5 Flash)
              Returns: summary, documentType, complianceScore,
                       keyFindings, riskFlags, extractedData
                  │
                  ▼
              Store in DocumentAnalysis table
              Create AuditLog entry
                  │
                  ▼
              Display in AI Insights tab of DocumentPreviewModal

17. Environment and Configuration¶

Required Environment Variables¶

Variable	Required	Description
`DATABASE_URL`	✅	PostgreSQL connection URL (pooled)
`DIRECT_URL`	✅	Direct Postgres URL (for Prisma migrations/push)
`AUTH_SECRET`	✅	JWT signing secret (`openssl rand -base64 32`)
`NEXTAUTH_URL`	✅	Canonical application URL (e.g. `https://firm.example.com`)
`NEXT_PUBLIC_APP_URL`	✅	Same as NEXTAUTH_URL (public-facing)
`GEMINI_API_KEY`	Recommended	Google Gemini API key (AI features disabled without it)
`LICENSE_SECRET`	Required in prod	HMAC secret for license signing (risk: forgery if missing)
`STORAGE_DRIVER`	Optional	`local` (default) \| `s3` \| `nas`
`STORAGE_LOCAL_PATH`	Optional	Override default `./uploads` path
`STORAGE_ENCRYPTION_KEY`	Recommended	AES-256-GCM key (hex, 64 chars) — files unencrypted if missing
`RESEND_API_KEY`	Optional	Transactional email (console-only if missing)
`EMAIL_FROM`	Optional	Sender address (e.g. `noreply@firmflow.co`)
`PAYSTACK_SECRET_KEY`	Optional	Payment processing (billing disabled if missing)
`AWS_ACCESS_KEY_ID`	If `STORAGE_DRIVER=s3`	S3 credentials
`AWS_SECRET_ACCESS_KEY`	If `STORAGE_DRIVER=s3`	S3 credentials
`STORAGE_S3_BUCKET`	If `STORAGE_DRIVER=s3`	S3 bucket name
`STORAGE_NAS_PATH`	If `STORAGE_DRIVER=nas`	NAS mount path
`LDAP_URL`	Optional	LDAP/AD integration (e.g. `ldap://dc.firm.local`)
`FCM_SERVER_KEY`	Optional	Firebase push notifications

Environment Validation¶

src/lib/env.ts validates all variables at startup via instrumentation.ts. Missing required vars throw and log loudly. Missing optional vars warn but allow startup.

18. Observability and Monitoring¶

Current State¶

Concern	Status	Implementation
Error logging	✅ Basic	`console.error` with context tags `[Module]`
Startup validation	✅ Active	`instrumentation.ts` → `validateEnv()`
Audit trail	✅ Active	Chained `AuditLog` in PostgreSQL
AI request logging	✅ Active	`AIRequestLog` (latency, token counts, success/fail)
Health endpoint	✅ Active	`GET /api/health` — DB connectivity + uptime
Sentry integration	🟡 Stub	`instrumentation.ts` has commented Sentry DSN hook
Load testing	✅ Done	Artillery YAML config in `load-test.yml`

Recommended Production Additions¶

Sentry DSN → uncomment stub in instrumentation.ts
Prometheus metrics endpoint → integrate prom-client
Grafana dashboard → connect to Prometheus
Log shipping → forward console to Loki or Cloudwatch

19. Data Flow Diagrams¶

Authentication Data Flow¶

[Browser]
    │ POST /api/auth/callback/credentials
    │ { email, password }
    ▼
[Middleware] Rate limit check (5/min)
    ▼
[NextAuth] Credentials provider authorize()
    ├── [LDAP] bind() attempt → success/fail
    └── [Prisma] user lookup → bcrypt.compare()
    ▼
[JWT] { id, firmId, role, twoFactorEnabled, deviceId }
    ▼
[Browser] HttpOnly cookie (AUTH_SESSION)
    ▼
[Middleware] Every subsequent request: auth() → session check → role check

Document Upload Data Flow¶

[Browser] POST /api/documents (multipart/form-data)
    ▼
[API Route]
    ├── auth() → firmId
    ├── multer/formData parse
    ├── License check (seat & feature gate)
    └── saveFile(buffer, filename, firmId)
            │
            ▼
    [StorageDriver.save()]
            ├── AES-256-GCM encrypt(buffer)
            └── Write to {firmId}/{timestamp}-{hash}.ext
    ▼
[Prisma] Document.create({ firmId, clientId, storagePath, ... })
    ▼
[AuditLog] "document.uploaded"
    ▼
[Browser] 201 { document }

AI Analysis Data Flow¶

[Browser] POST /api/documents/[id]/analyze
    ▼
[API] auth() → firmId check → document lookup
    ▼
[Storage] readFile(storagePath) → decrypt → Buffer
    ▼
[Genkit] documentAnalysisAgentFlow({
    fileBase64: buffer.toString('base64'),
    fileName, mimeType, documentId
})
    ▼
[Google Gemini 2.5 Flash] Analysis
    ▼
[Prisma] DocumentAnalysis.create({ summary, riskFlags, extractedData, complianceScore })
    ▼
[Browser] { summary, complianceScore, riskFlags, extractedData }

This document reflects the codebase state as of firmflow. v1.2.0 (February 2026). Architecture decisions are documented to support onboarding of new engineers, security audits, and enterprise procurement due diligence.

Maintainer: firmflow. Engineering
Classification: Internal Technical Reference