# Odiverse — Full Product Documentation

> The AI operating system for small and mid-market businesses. NVIDIA Inception member. Own GPU infrastructure. Human-in-the-loop by design.

## Overview

Odiverse is building the AI operating system for small businesses. Odi is an autonomous AI agent — your first AI team member — that runs your entire back office: invoicing, accounting, taxes, payroll, and treasury. Not software, not a chatbot. A team member that proposes actions and waits for your confirmation before executing.

Odiverse operates across 11 countries through three entities:
- **Odiverse Inc.** — Wilmington, DE, USA
- **BIAI Technology Project S.L.** — Granada, Spain (CIF B75473223)
- **Odiverse Limited** — Dublin, Ireland

**Supported countries**: Spain (ES), United States (US), Ireland (IE), Portugal (PT), France (FR), Germany (DE), Italy (IT), United Kingdom (GB), Canada (CA), Mexico (MX), Brazil (BR).

**Core principle**: AI serves, AI does not command. GPU for interpretation and conversation. Deterministic code for tax calculations, accounting rules, and compliance. Human confirmation on every write operation.

---

## Odi — The AI Agent

Odi is an autonomous AI agent that:

- Understands natural language commands in English and Spanish
- Issues invoices from verbal descriptions
- Processes received invoices via OCR (reads PDFs and photos)
- Records journal entries automatically
- Calculates payroll with tax withholdings
- Reconciles bank transactions
- Prepares tax filings
- Alerts about upcoming deadlines and anomalies
- Detects duplicate invoices and tax errors
- Explains financial concepts in plain language
- Deep-links into any module from the chat (open an invoice, navigate to a view)
- Handles frustrated users with empathetic recovery
- Never says "I don't understand" — always guides, suggests, or redirects

Odi operates on a strict principle: **it proposes, you decide**. No invoice, no tax filing, no payment happens without your explicit confirmation.

### Architecture: AI serves, AI does not command
- **GPU (LLM)**: interprets user intent, converses, searches, explains
- **CPU (code)**: validates, calculates, enforces rules. Taxes are filed when code validates and the user confirms — never because the LLM decided
- **55 tools** across 14 modules (invoicing, accounting, banking, treasury, fiscal, payroll, contacts, CRM, calendar, company, navigation, onboarding, employee portal), permission-filtered before the LLM context — if a user lacks payroll permission, payroll tools are invisible to the agent
- **Human-in-the-loop**: all write operations (create_invoice, create_journal_entry, reconcile_transactions, etc.) return a preview with `requires_confirmation=True`. Nothing touches the database without explicit user approval
- **Immutable audit trail**: every action is recorded — who asked, what the AI proposed, what the human approved, what was executed. Event sourcing architecture: never DELETE, always append
- **Conversational fallback**: multi-turn context via Redis, Odi always responds meaningfully using real company data

---

## Core Modules

### Invoicing
- Issue and receive invoices with automatic journal entries
- OCR: upload a PDF and Odi extracts all data (supplier, amount, tax, line items)
- Batch upload: process up to 15 invoices at once with NDJSON streaming
- Professional PDF generation with customizable templates
- Rectifying invoices / credit notes
- Partial and full payment tracking
- VeriFactu compliance (Spain): SHA-256 hash chain, QR code, SOAP submission, XAdES signing
- Immutable once issued (event sourcing architecture)

### Accounting
- Full chart of accounts per country:
  - Spain: PGC (415 accounts, groups 1-7)
  - United States: US GAAP
  - Ireland: FRS 102
  - Other countries: localized chart of accounts via jurisdiction modules
- Automatic journal entries from every invoice, expense, and payroll
- Trial Balance (Sumas y Saldos), P&L (PyG), Balance Sheet
- Event sourcing: immutable entries, complete audit trail — never DELETE, always append
- Manual and automatic journal entry creation

### Treasury
- Bank reconciliation with AI scoring
- Cash flow forecast (13 weeks)
- Financial instruments: accounts, credit lines, loans, leasing, factoring, cards, tax deferrals (7 types)
- Payment file generation (SEPA for EU, ACH for US)
- Real-time net position dashboard
- Open Banking via TrueLayer (persistent DB, encrypted tokens, auto-refresh)
- Multi-format bank import: CSV, XLSX, XLS, Norma 43/N43 with auto-detection
- Auto-categorization of bank transactions

### Payroll
- Automatic salary calculation with social security and tax withholdings
- Contract management with SEPE codes (8 subtypes)
- Progressive income tax by territory (common, Basque Country, Navarra for Spain)
- Social security contribution bases by professional group
- Occupational accident/disease rates by CNAE
- Payroll incidents (sick leave, maternity)
- Professional payslip PDFs with full breakdown
- Approve/pay workflow
- Batch processing and OCR batch upload
- Extra payments (pagas extra) and severance/offboarding (finiquito)
- SEPA remittances for bulk payment
- Dry-run simulation mode
- Payroll engine abstraction for multi-country support

### Tax / Fiscal
- Tax calendar with deadline alerts (38 obligations for Spain 2025-2026)
- Pre-calculated tax filings
- Multi-territory tax engine (SSOT): IVA/IGIC/IPSI (Spain), Sales Tax (US), VAT (Ireland/EU), and more
- Territory-aware automatic rate selection based on invoice postal codes
- Tax models: 303, 111, 115, 390, 200, 347, 190, 180 (Spain); Modelo 420 IGIC (Canary Islands); IPSI (Ceuta/Melilla)
- BOE export format
- Recargo de equivalencia support
- Tax provider abstraction per country for multi-jurisdiction filing
- e-Invoice provider abstraction (VeriFactu ES, Peppol IE, future integrations)

### CRM
- Pipeline kanban board with drag-and-drop
- Activities, tags, and reports
- Odi integration (3 dedicated intents)
- Lead tracking and conversion

### Calendar
- Month and week views
- Events CRUD with Odi integration
- Fiscal deadline integration

### Employee Portal
- Employee self-service: payslips, vacation requests, time tracking (RD 8/2019 compliant, CSV/PDF export)
- Contract viewing and document access
- Dedicated Odi agent with 13 intents: payslip, vacation, time tracking, documents, help, medical leave, salary, benefits, labor rights, contract, training, expense, workplace concern
- Unified authentication via main JWT system

### Dashboard
- KPIs: revenue, expenses, pending collections, pending payments
- Income vs Expenses chart (12 months)
- Upcoming deadlines
- Recent activity
- All data updates in real time

### Company Master Data (Mi Empresa)
- 7 editable sections with data provenance tracking
- OCR for 7 document types: articles of incorporation, tax ID, census declaration, bank ownership certificate, power of attorney, and more
- Odi integration with deep links and suggestions

### Configuration
- RBAC with 9 template roles, company-custom roles, and per-user permission overrides
- 80+ granular permissions (module.submodule.action format) with N-level wildcards
- Audit log viewer
- Usage analytics dashboard
- Invoice template customization
- Locale/i18n settings

---

## Multi-Jurisdiction Architecture

Odiverse supports 11 countries through a modular jurisdiction system:

- **Account mapping**: localized chart of accounts per country (PGC, US GAAP, FRS 102, and country-specific standards)
- **Tax providers**: pluggable tax calculation and filing per jurisdiction
- **Chart of accounts per country**: automatic seeding on company creation
- **e-Invoice providers**: VeriFactu (Spain), Peppol (Ireland), with extensible provider interface
- **Payroll engine abstraction**: country-specific social security, income tax, and contribution calculations
- **Jurisdiction modules**: `backend/jurisdictions/` with `JurisdictionConfig` base class defining tax rates, compliance flags, and UI visibility per country
- **Frontend adaptation**: automatic UI changes based on company country (hides VeriFactu for non-Spanish companies, filters fiscal tabs, adapts tax ID labels)
- **API endpoint**: `GET /api/jurisdiction` returns country-specific configuration
- **Registration flow**: reads country cookie, sets company.country + locale + currency + timezone

**Supported countries**: ES, US, IE, PT, FR, DE, IT, GB, CA, MX, BR.

---

## Security & Compliance

### Authentication & Access Control
- **2FA TOTP**: full two-factor authentication with QR code setup, TOTP verification on login, and secure disable flow
- **Token rotation with blacklist**: dual-token system (access 30min in-memory + refresh 7d httpOnly cookie). Refresh tokens blacklisted on rotation and logout. Redis-backed blacklist with in-memory fallback
- **Access tokens never in localStorage**: stored only in JavaScript memory variable, immune to XSS. Silent refresh on page reload via httpOnly cookie
- **Session invalidation**: `invalidate_user_sessions()` revokes all tokens on password change, reset, or 2FA disable
- **RBAC**: 9 template roles, 80+ granular permissions with N-level wildcards, per-user overrides
- **Rate limiting**: global 200 req/min per user/IP (Redis-backed) + per-endpoint limits for auth (20/15min), GDPR (10/15min), password change (5/15min), 2FA operations
- **Social login**: Google OAuth 2.0 (active), Apple Sign-In (backend complete)

### Audit & Monitoring
- **Audit trail**: every authenticated API request logged (method, path, action, entity, status, response time). Sensitive fields auto-sanitized
- **Usage analytics**: view enter/leave/navigation tracking with 30s buffer flush
- **Sentry integration**: error tracking in production with PII redaction

### Prompt Injection Protection
- **Input sanitization**: `orchestrator/sanitize.py` truncates, strips tags, detects and logs injection attempts before LLM processing
- **Output validation**: redacts database strings, API keys, and file paths from LLM responses
- **System prompt hardening**: anti-injection preamble in all system prompts
- **User-facing safety**: never exposes stack traces, SQL, UUIDs, or technical errors

### Compliance Standards
- **ISO 27001**: international information security management. Regular audits, risk assessment, incident response
- **ENS** (Spain): compliance with National Security Framework (RD 311/2022)
- **GDPR**: full EU data protection compliance. DPO, ARCO-POL rights, 72h breach notification, data export, anonymization, retention policies
- **VeriFactu** (Spain): immutable invoice chain via event sourcing, SHA-256 hash, QR verification, SOAP submission
- **e-Invoicing** (Ireland): prepared for 2028 mandate, EN 16931 structured invoices via Peppol

### Infrastructure & Data Sovereignty
- **Own servers** physically located in Spain/EU (Hetzner dedicated), not shared cloud
- **Own GPU infrastructure**: NVIDIA Inception member building hybrid inference — NVIDIA B200 GPUs via vLLM for data-sensitive operations (OCR, classification), Anthropic Claude API for complex reasoning
- **Data sovereignty by design**: financial data (invoices, payroll, bank statements) processed on own EU infrastructure, never transits to third-party APIs for sensitive operations
- Encryption: TLS 1.3 in transit, AES-256 at rest
- HSTS with preload enabled
- CORS restricted to explicit origin whitelist
- Daily encrypted backups to Cloudflare R2 (90-day retention)
- Cloudflare CDN + WAF + Bot Fight Mode in front of all public domains

---

## Email System

- **Provider**: Resend API with verified domain (odiverse.com)
- **Branded templates**: shared HTML layout with logo, brand typography, and accent bar
- **Template types**: email verification (6-digit code), password reset (CTA + fallback URL), invoice delivery (PDF attachment + tracking pixel), waitlist confirmation
- **Per-company sender addresses**: customizable From address
- **Tracking**: pixel-based open tracking for invoice emails
- **DNS**: DKIM, SPF, and MX records configured

---

## Internationalization (i18n)

- **Framework**: next-intl with 6 UI languages × 3,100+ keys × 78 namespaces
- **UI languages**: English, Spanish, Portuguese, French, German, Italian
- **Coverage**: 100% — sidebar, tabs, KPIs, empty states, dialogs, badges, Odi suggestions, auth flows, error messages, email templates. Zero hardcoded visible strings
- **Locale system**: single control point (`company.locale`) embedded in JWT. Backend middleware sets locale per-request. Frontend reads from CompanyContext
- **Supported locales**: es-ES, es-MX, en-US, en-GB, en-IE, en-CA, de-DE, fr-FR, pt-PT, pt-BR, it-IT (11 total)
- **Auto-detection**: Accept-Language + country cookie for language, timezone for country
- **Number/currency formatting**: centralized in `locale.ts` (frontend) and `fiscal_formatting.py` (backend) — never hardcoded
- **Backend errors**: 124 error message keys × 6 languages. 4 email templates × 6 languages

---

## Technical Architecture

- **Frontend**: Next.js 16 + React 19 + TypeScript strict + Tailwind CSS v4 + shadcn/ui
- **Backend**: Python 3.12 + FastAPI (async) + SQLAlchemy async + asyncpg + PostgreSQL 16
- **AI/LLM**: Claude Sonnet (conversational AI, complex reasoning) + own GPU infrastructure (NVIDIA B200, vLLM) for data-sensitive inference. 55 tools via pydantic-ai-slim. LiteLLM for model routing. Human-in-the-loop on all write operations
- **Infrastructure**: Docker Compose, Redis 7, own dedicated servers in EU (Hetzner, Spain). NVIDIA Inception member
- **Email**: Resend API with branded templates and tracking
- **Observability**: Sentry (error tracking, PII redaction), PostHog (product analytics)
- **Testing**: 1,164 backend tests (928 passing in CI) + 53 E2E specs (Playwright) + 21 dedicated security tests
- **CI/CD**: GitHub Actions — ruff check + format, pytest, tsc + eslint, auto-deploy on push to main
- **PDF generation**: WeasyPrint
- **Open Banking**: TrueLayer integration (persistent DB, encrypted tokens)

---

## Agent-Native Platform (connect external AI agents)

Odiverse exposes first-class APIs for external AI agents — live in production, gated to beta customers:

- **Remote MCP server**: `https://app.odiverse.com/api/mcp` (JSON-RPC over HTTP). Tools are filtered by the authorizing user's permissions before the model sees them
- **OAuth 2.1 + Dynamic Client Registration (RFC 7591)**: discovery at `https://app.odiverse.com/.well-known/oauth-authorization-server` and `.../.well-known/oauth-protected-resource`. Unauthenticated MCP calls return 401 with a `WWW-Authenticate` resource-metadata pointer, so compliant clients self-configure
- **Scoped agent tokens**: agent permissions = granted scopes ∩ the human user's permissions. Per-agent rate limits. Tokens managed and revocable by humans only — agents cannot mint or revoke tokens
- **Human approval queue**: sensitive writes attempted by an agent (issue invoice, pay payroll, send remittance) queue for human review and execute with the approving human's authority. Irreversible legal filings (tax submission) are hard-blocked for agents
- **Idempotency keys** on writes; audit trail records the origin of every action (human / Odi / which external agent)
- **CLI**: `odiverse` (typed flags generated from the live OpenAPI spec, `--json` output) and `odiverse-mcp` (local MCP server over the same tool surface)
- **Microsoft 365 / Copilot connector** generated from the same OpenAPI spec, authenticating against the same OAuth server
- Developer documentation: https://odiverse.com/us/developers

---

## Pricing

| Plan | Price | Target | Key Features |
|------|-------|--------|--------------|
| Starter | €29/month ($29, £25) | Freelancers, solopreneurs | Unlimited invoicing, accounting, Odi AI agent, 1 user |
| Pro | €79/month ($79, £69) | Growing SMEs | All Starter + Treasury, Payroll, Unlimited Odi, multi-entity, priority support |
| Enterprise | Contact sales | Mid-market companies | Unlimited users, SLA, dedicated onboarding, consolidation, custom integrations |
| LATAM | MX$399/$999, BR R$79/R$199 | Latin America | Local currency pricing, same features |

All plans include Odi (AI agent with human-in-the-loop), unlimited invoices, bank connections, and 6-language support.

---

## Company

Odiverse operates across 11 countries through three entities:
- **Odiverse Inc.** — 901 N Market St, Suite 100, Wilmington, DE 19801, USA
- **BIAI Technology Project S.L.** — Av. del Conocimiento 41, A303, 18016 Granada, Spain
- **Odiverse Limited** — Harcourt Centre Block 4, Harcourt Road, Dublin, D02 HW77, Ireland

Founded in 2025. NVIDIA Inception program member. Own GPU infrastructure (NVIDIA B200s).

**Mission**: Give every small business an AI team member that handles the back office, so founders can focus on what matters.

**What makes Odiverse different from other AI accounting tools**:
1. **Not an API wrapper** — own GPU infrastructure for data-sensitive operations, not just a prompt on top of OpenAI/Google
2. **Human-in-the-loop** — every write operation requires explicit user confirmation. AI proposes, you decide
3. **Deterministic accounting** — tax calculations, accounting rules, and compliance logic run in code, not in the LLM
4. **Data sovereignty** — financial data stays on own EU servers, never transits to third-party AI APIs for sensitive operations
5. **Multi-country native** — single platform for 11 countries with localized tax, compliance, and chart of accounts
6. **Immutable audit trail** — event sourcing architecture, every action traceable from request to execution

**Website**: https://odiverse.com
**US**: https://odiverse.com/us
**Spain**: https://odiverse.com/es
**Ireland**: https://odiverse.com/ie
**Contact**: info@odiverse.com