Platform Overview¶
firmflow. v1.2.0 — On-Premise Nigerian Accounting Hub
This document provides a high-level overview of the firmflow. platform for IT administrators, enterprise buyers, and technical evaluators.
Architecture Summary¶
firmflow. is a monolithic Next.js 15 application that bundles the staff dashboard, client portal, REST API, and AI engine into a single deployable Docker container. The architecture is intentionally simple to reduce operational overhead for on-premise IT teams.
Internet
│
▼
[ Nginx / Caddy ] (TLS termination, port 443→9002)
│
▼
[ firmflow. App Container ] (Next.js 15, port 9002)
├── Staff Dashboard (/dashboard/*)
├── Client Portal (/portal/[firmSlug]/*)
├── REST API (/api/*)
└── Marketing Site (/)
│
├──▶ [ PostgreSQL 14+ ] (port 5432)
└──▶ [ File Storage ] (Local FS / NAS / S3)
Outbound-only (optional):
├──▶ Google Gemini AI API (TLS 1.3)
├──▶ Resend Email API (TLS 1.3)
└──▶ Paystack Payments API (TLS 1.3)
Core Modules¶
🏢 Client Management¶
Clients are the accounting firm's end-clients. Each client record stores:
- Company name, email, phone
- CAC RC Number (Corporate Affairs Commission registration)
- FIRS TIN (Tax Identification Number)
- Risk score (0–100, AI-generated)
- Portal access credentials
- Linked documents, compliance tasks, signature requests
📁 Document Vault¶
- Hierarchical storage:
firmId/timestamp-hash.ext - AES-256-GCM encryption at rest on all storage drivers
- Versioning with parent document linkage
- MIME-type detection and size tracking
- Bulk ZIP download and extraction API
✍️ e-Signatures¶
Complete in-house e-signature workflow: - Drag-and-drop field placement (signature, initials, date, text, checkbox) - Ordered signing (multiple recipients with sequence) - Token-based public signing page (no client account required) - Full event log: sent, opened, signed, declined, completed - Linked directly to engagement letter templates
🧠 SmartRequestAI™¶
14 AI flows running on Google Gemini 2.5 Flash:
| Flow | Purpose |
|---|---|
| Smart Request Generation | AI document checklists by client type |
| Document Analysis | Summary, risks, compliance score |
| Compliance Auto-Solver | AI-powered checklist completion |
| Client Risk Analysis | CBN/AML risk scoring |
| Tax Engine | CIT/VAT/WHT computation |
| Tax Filing Execution | FIRS e-filing guidance |
| Document Review | Compliance flag detection |
| Firm Explorer | Analytics and insights |
| Firm Performance Audit | KPI report generation |
| Industry Benchmark | Sector comparison |
| Data Extractor | Batch data extraction to CSV |
| Vault Chat | Conversational document Q&A |
| Client Email Draft | Professional email composition |
| Portal Filing Agent | Client portal filing guidance |
🛡️ Compliance Calendar¶
- FIRS/LIRS task calendar with predefined Nigerian tax categories
- Deadline tracking per client per period
- Checklist items with document attachment proof
- AI auto-solver for standard checklists
- Billing value tracking per compliance task
🏗️ Tax Prep Pipeline¶
7-stage Kanban pipeline:
| Stage | Description |
|---|---|
| GATHERING | Collecting client documents |
| REVIEW | Internal staff review + AI analysis |
| PREPARATION | Return/form preparation |
| PARTNER_REVIEW | Partner sign-off |
| CLIENT_APPROVAL | Client review and signature |
| FILING | Submitted to FIRS/LIRS |
| ARCHIVED | Complete and filed |
All 9 Nigerian tax types supported with statutory FIRS/LIRS deadlines.
Security Architecture¶
Defence in Depth
firmflow. implements multiple independent layers of security. Comprise any single layer and the others continue to protect client data.
| Control | Implementation |
|---|---|
| Authentication | NextAuth v5 + bcrypt (cost 12) + LDAP fallback |
| MFA | TOTP — secrets encrypted with AES-256-GCM (FIELD_ENCRYPTION_KEY) |
| Device Binding | Session fingerprint: btoa(userAgent + IP) validated per-request |
| Rate Limiting | IP-based in-process rate limiter (20/min auth, 5/min signatures) |
| RBAC | 5 roles: SUPER_ADMIN → FIRM_ADMIN → PARTNER → STAFF → CLIENT |
| Field Encryption | AES-256-GCM on MFA secrets, signature hashes, and API tokens |
| Encryption in Transit | TLS 1.3 enforced (Nginx) |
| Encryption at Rest | AES-256-GCM on all stored files (Local, NAS, S3) |
| Audit Trail | Cryptographic SHA-256 hash chain — tamper-evident |
| CSP Headers | Strict — no eval in production |
| CORS | Restricted to NEXT_PUBLIC_APP_URL |
| Path Traversal | safePath() validation on all storage ops |
| WAF | ModSecurity + OWASP Core Rules on Kubernetes Ingress |
| Egress Control | Kubernetes NetworkPolicy: default-deny, TLS-only AI allowlist |
NDPR Compliance¶
| Requirement | Implementation |
|---|---|
| Data Localisation | On-premise storage — no data leaves the server |
| Right of Access | One-click DSAR export via /api/compliance/dsar |
| Data Minimisation | 7-year retention service auto-purges archived documents |
| PII Protection | AI Privacy Gateway scrubs BVN, TIN, and phone numbers before AI calls |
| Accountability | Cryptographic audit log provides tamper-proof evidence trail |
| DPO Readiness | docs/NDPR_AUDIT_REPORT.md provides formal compliance assessment |
Nigerian Regulatory Alignment¶
| Regulation | How firmflow. Addresses It |
|---|---|
| NDPA 2023 | On-premise; data export API; access logs; retention planning |
| FIRS CIT | Companies Income Tax job tracking, 6-month deadline |
| FIRS VAT | Monthly VAT deadline (21st), WHT (21st) |
| LIRS PAYE | Monthly payroll tax (10th of following month) |
| SCUML AML/CFT | Mandatory screening step in onboarding wizard |
| CAC Compliance | RC Number stored and verified |
| FIRS TIN | TIN stored and verified in onboarding |
| ICAN Standards | Engagement templates flagged isIcanCompliant |
| CBN KYC | Triple-check: CAC + TIN + SCUML |
License Editions¶
| Edition | Max Seats | SmartRequestAI™ | Advanced Audit | API Access |
|---|---|---|---|---|
| Trial | 3 | Limited | ❌ | ❌ |
| Basic | 5 | ❌ | ❌ | ❌ |
| Professional | 25 | ✅ | ✅ | ❌ |
| Enterprise | Unlimited | ✅ | ✅ | ✅ |
See Billing & Licensing for pricing and activation details.
System Requirements¶
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPUs | 4 vCPUs |
| RAM | 4 GB | 16 GB |
| Storage | 50 GB SSD | 500 GB SSD / NAS |
| OS | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS |
| Database | PostgreSQL 14 | PostgreSQL 16 |
| Node.js | 20 LTS | 20 LTS |
See Installation Guide for full setup instructions.