Officia MENA

Officia MENA is a modular, AI-powered Business Operating System and ERP platform specifically tailored for the MENA (Middle East and North Africa) region. It consolidates accounting, invoicing, inventory management, HR, subscriptions, banking operations, and AI-driven inbox management into a single, cohesive SaaS product.

Security & Readiness Disclaimer: This project is currently in the MVP/Architecture Hardening phase. It is not yet ready for production use with real financial data. Features like Tenant Isolation, RBAC, and ZATCA compliance are actively being audited and fortified.

🌍 Target Markets & Regulations

• Primary Focus: MENA region, particularly Saudi Arabia (KSA) and UAE.
• ZATCA (KSA): The system aims to support ZATCA Phase 2 compliance.
  • Current Status: Basic TLV/Base64 QR code generation is implemented. Full Phase 2 (XML generation, UBL profiles, cryptographic stamping, clearance flows) is experimental/pending.
• Multi-Tenant SaaS: Designed to serve multiple independent businesses securely from a single deployment.

🏗 Architecture & Stack

Officia MENA is built on a modern, robust web stack:

• Framework: Next.js 15 (React 19)
• Language: TypeScript
• Database: PostgreSQL
• ORM: Drizzle ORM
• Authentication: NextAuth Credentials with Drizzle-backed users and bcrypt password verification
• Billing & Subscriptions: Stripe
• AI Integration: Vercel AI SDK (Anthropic & Google providers for fallback and cost optimization)
• Styling: Tailwind CSS v4, Framer Motion
• Testing: Vitest, Zod (validation)

📂 Directory Structure

officia-mena/
├── src/
│   ├── app/                # Next.js App Router (Public pages, Auth, Dashboard, API)
│   ├── components/         # Reusable UI components
│   ├── lib/                # Core Business Logic & Infrastructure
│   │   ├── accounting/     # Ledger, postings, chart of accounts
│   │   ├── ai/             # AI tools, prompts, providers
│   │   ├── auth/           # NextAuth, tenant resolution and RBAC
│   │   ├── billing/        # Subscription management
│   │   ├── db/             # Drizzle config and schema definitions
│   │   │   └── schema/     # Domain-driven DB schemas (tenants, users, invoices, etc.)
│   │   ├── hr/             # HR management
│   │   ├── inventory/      # Inventory and stock control
│   │   └── stripe/         # Stripe API and webhooks
├── agrinexus-law/          # Git submodule (Legal logic/Contracts)
└── tests/                  # Unit and integration tests

🚀 Getting Started

1. Environment Variables

Create a .env.local file based on the required variables (check .env.vercel or .env.local.backup if available). At a minimum, you will need:

# Database
DATABASE_URL="postgres://user:password@localhost:5432/officia"

# Authentication
AUTH_SECRET="use-a-long-random-secret"
ENABLE_DEMO_LOGIN="false"

# Stripe
STRIPE_SECRET_KEY="..."
STRIPE_WEBHOOK_SECRET="..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="..."

# AI Providers
ANTHROPIC_API_KEY="..."
GOOGLE_GENERATIVE_AI_API_KEY="..."
AI_GATEWAY_API_KEY="..." # enables cross-provider fallback
AI_GATEWAY_PRIMARY_MODEL="anthropic/claude-sonnet-4.5"
AI_GATEWAY_FALLBACK_MODEL="google/gemini-2.5-flash"

# Protects scheduled Maestro and reporting endpoints
CRON_SECRET="use-a-long-random-secret"

# Production connectors
RESEND_API_KEY="..."
REPORT_FROM_EMAIL="Officia MENA <[email protected]>"
OPEN_BANKING_API_URL="https://your-certified-provider.example"
OPEN_BANKING_ACCESS_TOKEN="..."
OPEN_BANKING_TENANT_ID="tenant-uuid-owning-this-consent"
OPEN_BANKING_ENV="sandbox"
ZATCA_API_URL="https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal"
ZATCA_CSID="..."
ZATCA_CSID_SECRET="..."
ZATCA_TENANT_ID="tenant-uuid-owning-this-csid"
ZATCA_ENV="sandbox"

Maestro's proactive monitor runs daily through /api/cron/maestro-monitor. It detects overdue receivables, delayed ZATCA reporting, expiring employee documents, low stock, and expiring inventory. The endpoint requires Authorization: Bearer $CRON_SECRET; authorized dashboard users can also trigger a scan from the Maestro inbox.

Maestro orchestration

Maestro routes each request to a finance, tax/ZATCA, HR, inventory, collections, or executive specialist and exposes only that specialist's required tools. The AI Control Center shows run status, latency, token usage, and routing without storing raw chat content. Memory is opt-in: users must explicitly ask Maestro to remember something, while company-wide memory can be changed only by admins and managers. Financial writes continue to require the Phase 2 approval workflow.

Enterprise Knowledge Engine

Uploaded PDFs are registered by SHA-256 checksum, versioned by filename, split with overlap while preserving page citations, and embedded into pgvector. Retrieval combines vector similarity with PostgreSQL full-text search through Reciprocal Rank Fusion. Active/effective dates and role ACLs are enforced before results reach Maestro. Retrieval telemetry stores query hashes and citation metrics, never the raw question.

2. Database & Drizzle

Ensure you have a PostgreSQL instance running.

# Install dependencies
npm install

# Generate Drizzle migrations
npm run db:generate

# Apply migrations to your local DB
npm run db:migrate

# (Optional) Open Drizzle Studio to inspect data
npm run db:studio

3. Running the Development Server

npm run dev

Open http://localhost:3000 with your browser to see the result.

🧪 Testing & CI/CD

Run the test suite using Vitest:

# Run unit tests
npm run test

# Run typechecking
npm run typecheck

# CI Check (Lint, Typecheck, Test, Build)
npm run ci

🤖 AI Providers & Usage

The platform utilizes a dual-provider AI setup (Anthropic and Google) via the Vercel AI SDK. This allows the system to intelligently switch models based on task complexity (e.g., OCR extraction vs. financial analysis) and handle API rate limits gracefully.

Maestro uses a human-in-the-loop governance layer. Financial drafts, external email, and ZATCA submissions are proposed first, approved by an authorized user, and executed by deterministic services with audit and idempotency controls. Maestro has no payment-initiation tool.

💳 Stripe Webhooks

Stripe is used for tenant subscriptions. Webhooks must be configured in your Stripe Dashboard to point to /api/webhooks/stripe to ensure subscription statuses remain synchronized with the local database.

🚧 Project Status: What's Complete vs. Experimental

✅ Complete / Solid Foundation:

• Database domain modeling (separated by business domains like HR, Inventory, Invoices).
• Multi-tenant foundational schemas (tenants, users, rbac).
• Modern Next.js 15 + React 19 integration.
• NextAuth Credentials authentication with fail-closed tenant resolution and RBAC.

🧪 Experimental / Under Refactoring:

• Accounting Engine: Large modules (ledger.ts, postings.ts) are currently monolithic and are scheduled for decomposition.
• Tenant Isolation: Application queries are tenant-scoped and defense-in-depth RLS migrations are included; production DB roles and policies must still be validated in deployment tests.
• ZATCA Phase 2: Full XML clearance flow is pending.
• Contracts Engine: Currently relies on a Git submodule (agrinexus-law). Integration boundaries are being redefined.