How cbrito475/saasfactura works
1. Overall shape
FacturaVE is a monorepo with three main runtime surfaces: a NestJS API in apps/api, a React/Vite SPA in apps/web, and shared domain libraries plus Prisma schema in packages/. The architecture is centered on a multi-tenant SaaS for Venezuelan invoicing, accounting, tax, and admin operations.
2. Backend entry point and composition
The API boots from apps/api/src/main.ts into AppModule, then composes many bounded modules. Cross-cutting infrastructure sits first: Prisma/PostgreSQL, Redis, tenant context middleware, and observability/audit interceptor. The API is structured as a set of Nest modules with clear internal layering.
3. Module layering pattern
Most business areas follow the same split: HTTP controllers at the edge, application services/use-cases for orchestration, domain services/entities/ports for rules, and Prisma repositories/adapters for persistence or external integration. This makes the architecture diagram strongly layered, with dependencies flowing inward from controllers to application to domain, and outward through ports to infrastructure.
4. Tenant, auth, and authorization boundary
Authentication is split into two domains:
- auth for tenant user access
- saas-auth for SaaS administrator access
These modules provide JWT strategies, guards, decorators, and repositories. Tenant isolation is enforced by a tenant context middleware plus guards like tenant.guard, permission.guard, onboarding.guard, and SaaS-specific role guards. This is one of the key architectural boundaries.
5. Core business domain: company operations
The business core is organized around modules such as empresa, sucursal, cliente, proveedor, producto, canal-venta, caja, contabilidad, nomina, operations, serie-numeracion, and fiscal-calendar. These modules handle master data, POS/cash handling, accounting movements, payroll, stock/aging calculations, numbering series, and fiscal period logic.
6. Tax and invoicing subsystem
Tax and invoicing are further split into specialized modules: tax-engine, tax-books, tax-declarations, invoicing, factura-compra, and retencion. These modules coordinate invoice emission, PDF generation, tax totals, IVA previews, purchase/sales books, withholding documents, and validation rules. The shared-domain package contributes reusable tax/calculation logic used by these services.
7. Accounting and fiscal record integrity
accounting provides journal entries, auto-posting, closures, financial statements, and legal books. The repo’s compliance-oriented design is reinforced by append-only fiscal rules in the database, and a hash-chain audit log in empresa_log. This means the architecture is not just CRUD; it includes tamper-evident fiscal records and verifiable logs.
8. Flows and job orchestration
The flows module is a dedicated workflow engine with flow definitions, execution entities, DSL persistence, step resolution, and action execution adapters. It is complemented by jobs, which handles queued work and retry policy. These two modules form the async/process-orchestration layer for tenant-specific automation.
9. External Services Manager
The esm module is the integration boundary for external services. It has production/emulator adapters, assignment resolution, cryptography, and service-account/admin workflows. In a diagram, this should sit between the app and external providers, abstracting environment-specific behavior behind ports and adapters.
10. Backend infrastructure
Persistence is Prisma + PostgreSQL, with repositories per module and a central Prisma service/module. Redis is present as a separate infrastructure module. The repository also includes generated dist/ output for the API, indicating build artifacts are committed or available in the tree, but the source of truth is under src/.
11. Frontend architecture
The SPA in apps/web is organized around route-level pages and reusable layout components. State is coordinated through AuthContext, EmpresaContext, and FeaturesContext. API access is centralized through lib/api.ts and lib/saas-api.ts, so the frontend depends on backend contracts rather than direct data access.
12. Frontend domain surfaces
The UI reflects the backend boundaries: business pages like dashboard, facturación, compras, contabilidad, inventario, nómina, productos, clientes, tributario; POS screens for caja/ventas; onboarding flows; and a separate SaaS admin area for empresas, usuarios, flujos, operaciones, ESM, and auditoría. That separation mirrors the backend’s tenant vs SaaS-admin split.
13. Shared packages
packages/shared-domain contains pure calculation and validation libraries for contabilidad, nomina, IVA, retenciones, IGTF, total factura, fiscal period, and RIF validation. packages/shared-types provides shared contracts. These packages are the lowest-level dependency layer and should be drawn as reusable, framework-agnostic building blocks used by both backend and, potentially, frontend contracts.
14. Database, seeds, and compliance assets
packages/prisma contains the Prisma schema, seed scripts, and manual SQL migrations, including security and hash-chain triggers. The database layer is not just storage; it encodes tenant security, append-only rules, and compliance constraints. There is also an uploads/ area under the API for generated artifacts such as PDFs.
15. Operational state
Per the README, the repository is currently in Phase 0 + Phase A, meaning the platform boots, supports signup, company creation, dashboard navigation, and log verification. The architecture already includes placeholders and modules for later phases, but many features are scaffolding or partially implemented rather than fully exposed end-to-end.
Main entry points: app.module.ts App module · prisma.module.ts Prisma DB · Dashboard.tsx Business UI · SaasEmpresas.tsx SaaS UI
Components 21
API
NestJS backend surface
- main · API process entrypoint
apps/api/src/main.ts - App module · Wires backend modules
apps/api/src/app.module.ts - Prisma DB · PostgreSQL/tenant context bridge
apps/api/src/infrastructure/database/prisma.module.ts - Redis · Shared Redis integration
apps/api/src/infrastructure/redis/redis.module.ts - Audit · Audit interceptor
apps/api/src/observability/audit.interceptor.ts - Auth · Tenant login, guards, and JWT strategy
apps/api/src/modules/auth/auth.module.ts - SaaS auth · SaaS admin access and roles
apps/api/src/modules/saas-auth/saas-auth.module.ts - Features · Feature flags and access rules
apps/api/src/modules/features/features.module.ts - Empresa · Company onboarding and fiscal config
apps/api/src/modules/empresa/empresa.module.ts - Core ops · Clientes, proveedores, productos, sucursales, series, caja
- Tax & billing · Invoicing, tax engine, declarations, retentions, books
apps/api/src/modules/invoicing/invoicing.module.ts - Accounting · Journal entries, closures, statements, legal books
apps/api/src/modules/accounting/accounting.module.ts - Flows & jobs · Workflow DSL, execution, queueing, retries
apps/api/src/modules/flows/flows.module.ts - ESM · External service manager with adapters
apps/api/src/modules/esm/esm.module.ts - Mail · Outbound email port and adapter
apps/api/src/modules/mail/mail.module.ts
Web
React/Vite frontend surface
- Web shell · App composition, layout, contexts, API clients
apps/web/src/App.tsx - Business UI · Dashboard, facturación, compras, contabilidad, POS, onboarding
apps/web/src/pages/Dashboard.tsx - SaaS UI · SaaS admin area for companies, users, flows, ESM, audit
apps/web/src/pages/saas/SaasEmpresas.tsx
Shared
Reusable packages and schema
- Shared domain · Tax, payroll, accounting calculations and validations
packages/shared-domain/src/index.ts - Shared types · Cross-package type contracts
packages/shared-types/src/index.ts - Schema · Prisma schema, seeds, and SQL rules
packages/prisma/schema.prisma
Connections 32
- main → App module: boots · Nest application starts from main into AppModule
- App module → Prisma DB: uses · Backend composes Prisma/PostgreSQL layer
- App module → Redis: uses · Backend composes Redis layer
- App module → Audit: wraps · Global audit/interceptor concern
- App module → Auth: loads · Tenant auth boundary
- App module → SaaS auth: loads · SaaS admin auth boundary
- App module → Features: loads · Feature gating and entitlement checks
- App module → Empresa: loads · Tenant onboarding and company management
- App module → Core ops: loads · Operational master-data modules
- App module → Tax & billing: loads · Tax, billing, and fiscal compliance modules
- App module → Accounting: loads · Ledger and reporting modules
- App module → Flows & jobs: loads · Workflow and async orchestration layer
- App module → ESM: loads · External service manager boundary
- App module → Mail: loads · Notification subsystem
- Auth → Prisma DB: persists · Tenant users and access state stored via Prisma
- SaaS auth → Prisma DB: persists · SaaS admins, users, and audit data stored via Prisma
- Empresa → Shared domain: calculates · Uses shared fiscal and accounting primitives
- Tax & billing → Shared domain: calculates · Uses shared tax/validation logic
- Accounting → Shared domain: calculates · Uses shared double-entry helpers
- Flows & jobs → Redis: queues · Async work and retries use Redis-backed infrastructure
- ESM → Prisma DB: persists · Service assignments and manager state stored via Prisma
- Web shell → Business UI: routes · Tenant UI is composed of business pages
- Web shell → SaaS UI: routes · Shell also serves SaaS admin pages
- Web shell → Shared types: types · Frontend consumes shared contracts
- Business UI → Auth: calls · Tenant UI authenticates against backend auth
- Business UI → Empresa: calls · Company onboarding and context APIs
- Business UI → Tax & billing: calls · Invoices, purchases, taxes, and accounting screens hit fiscal APIs
- SaaS UI → SaaS auth: calls · SaaS admin UI authenticates against SaaS auth
- SaaS UI → Features: calls · Feature management screens use entitlement APIs
- SaaS UI → ESM: calls · ESM admin screens use integration APIs
- Prisma DB → Schema: driven by · Database layer is defined by Prisma schema and SQL rules
- Shared domain → Schema: aligned with · Business rules reflect persisted fiscal model