Technical Documentation

1.System Architecture

Xpensio is a cloud-native, multi-tenant enterprise expense management platform built as a monorepo. It consists of four distinct application layers that communicate over HTTPS REST APIs, with shared infrastructure for authentication, notifications, and ERP integration.

1.1 High-Level Architecture

1.2 Technology Stack

1.3 Infrastructure

1.4 Multi-Tenancy Model

Xpensio uses a shared database, shared schema multi-tenancy approach. Every database record contains an orgId field that is automatically injected and validated on every query. A middleware layer extracts the orgId from the JWT token and verifies it against the requested resource, making cross-organization data leakage structurally impossible at the service layer.

1.5 Expense Workflow State Machine

Every expense follows a strict state machine with role-based transitions:

2.Project Structure

The project is a pnpm monorepo with four workspace packages. Each package is independently deployable and has its own dependencies managed via pnpm workspaces.

2.1 Repository Root

Claude_Proj1/                          # Repository root
├── apps/
│   ├── backend/                       # NestJS API server
│   ├── web/                           # Next.js web dashboard
│   ├── mobile/
│   │   └── expense_mobile/            # Flutter mobile app
│   └── website/                       # Next.js marketing site
│       └── src/
├── website/                           # Landing page (Next.js)
├── docs/                              # Technical documentation
├── docker-compose.yml                 # Local development stack
├── docker-compose.prod.yml            # Production override (VPS)
├── package.json                       # Root workspace config
├── pnpm-workspace.yaml                # pnpm workspace definition
└── .env                               # Root environment variables

2.2 Backend Structure (apps/backend/)

apps/backend/
├── src/
│   ├── main.ts                        # NestJS bootstrap, CORS, Swagger
│   ├── app.module.ts                  # Root module, global guards
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── auth.service.ts            # Login, register, token management
│   │   ├── auth.controller.ts         # /auth/* endpoints
│   │   ├── jwt.strategy.ts            # JWT validation strategy
│   │   ├── jwt-refresh.strategy.ts    # Refresh token strategy
│   │   └── guards/
│   │       ├── jwt-auth.guard.ts
│   │       └── roles.guard.ts
│   ├── users/
│   │   ├── users.module.ts
│   │   ├── users.service.ts           # User CRUD, import, password reset
│   │   └── users.controller.ts        # /users/* endpoints
│   ├── expenses/
│   │   ├── expenses.module.ts
│   │   ├── expenses.service.ts        # Core workflow, fraud detection
│   │   ├── expenses.controller.ts     # /expenses/* endpoints
│   │   └── dto/
│   ├── receipts/
│   │   ├── receipts.module.ts
│   │   ├── receipts.service.ts        # OCR pipeline orchestration
│   │   └── receipts.controller.ts     # /receipts/scan endpoint
│   ├── notifications/
│   │   ├── notifications.module.ts
│   │   ├── notifications.service.ts   # Email + push dispatch
│   │   └── notifications.controller.ts
│   ├── identity/
│   │   ├── identity.module.ts
│   │   ├── identity.service.ts        # IDENTITY_PROVIDER routing
│   │   └── adapters/
│   │       ├── sap.adapter.ts         # SAP ECC/S4HANA RFC adapter
│   │       ├── oracle.adapter.ts      # Oracle ERP adapter
│   │       ├── logo.adapter.ts        # Logo Tiger adapter
│   │       └── none.adapter.ts        # No-op adapter (dev/default)
│   └── common/
│       ├── decorators/
│       ├── filters/                   # Global exception filter
│       ├── interceptors/              # Logging, transform
│       └── pipes/                     # Validation pipe
├── prisma/
│   ├── schema.prisma                  # Database schema (source of truth)
│   ├── migrations/                    # Prisma migration history
│   ├── seed.ts                        # Development seed
│   └── seed-demo.js                   # Demo org seeder
├── Dockerfile                         # Multi-stage production build
├── .env                               # Backend environment variables
└── tsconfig.json

2.3 Web Frontend Structure (apps/web/)

apps/web/
├── src/
│   ├── app/                           # Next.js 14 App Router
│   │   ├── layout.tsx                 # Root layout, providers
│   │   ├── page.tsx                   # Landing redirect
│   │   ├── login/page.tsx             # Login page
│   │   ├── forgot-password/           # Password reset flow
│   │   └── dashboard/
│   │       ├── layout.tsx             # Dashboard shell + sidebar
│   │       ├── expenses/page.tsx      # Expense list + actions
│   │       ├── expenses/new/page.tsx  # New expense form
│   │       ├── approvals/page.tsx     # Manager approval queue
│   │       ├── finance/page.tsx       # Finance processing
│   │       ├── reports/page.tsx       # Reports + Excel export
│   │       ├── users/page.tsx         # Admin user management
│   │       ├── settings/page.tsx      # User settings + password
│   │       └── admin/page.tsx         # Org configuration
│   ├── components/                    # Shared UI components
│   │   ├── ExpenseCard.tsx
│   │   ├── ApprovalQueue.tsx
│   │   ├── NotificationBell.tsx
│   │   └── UserImportModal.tsx
│   ├── lib/
│   │   ├── api.ts                     # Axios API client + interceptors
│   │   └── store.ts                   # Zustand global state
│   └── types/                         # TypeScript type definitions
├── e2e/
│   ├── helpers.ts                     # Shared Playwright helpers
│   ├── production/                    # Production E2E test suites
│   └── playwright.config.ts
└── next.config.js

2.4 Mobile Structure (apps/mobile/expense_mobile/)

expense_mobile/
├── lib/
│   ├── main.dart                      # App entry point, Firebase init
│   ├── screens/
│   │   ├── login_screen.dart
│   │   ├── expenses_screen.dart       # Expense list
│   │   ├── new_expense_screen.dart    # Create expense + OCR
│   │   ├── approvals_screen.dart      # Manager approvals
│   │   ├── companies_screen.dart      # Sub-company selector
│   │   └── profile_screen.dart        # User settings
│   ├── services/
│   │   ├── api_service.dart           # HTTP client
│   │   ├── auth_service.dart          # Token management
│   │   └── notification_service.dart  # FCM push handling
│   └── widgets/                       # Reusable Flutter widgets
├── ios/
│   ├── Runner/
│   │   └── Info.plist                 # iOS permissions (camera, photo)
│   └── Podfile
├── android/
│   └── app/
│       ├── build.gradle
│       └── google-services.json       # Firebase config (Android)
└── pubspec.yaml                       # Flutter dependencies

3.Database Schema

Xpensio uses PostgreSQL 15 with Prisma ORM (v5.8.0). The schema enforces multi-tenancy at the data layer via orgId foreign keys. All migrations are tracked in apps/backend/prisma/migrations/.

3.1 User Model

3.2 Expense Model

3.3 Organization Model

3.4 SubCompany Model

3.5 RefreshToken Model

3.6 Notification Model

14. Release Notes (v1.4 — April 2026)