# anasse84/fisca architecture

> Architecture diagram of the GitHub repository anasse84/fisca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anasse84/fisca
- Repository: https://github.com/anasse84/fisca

## Overview

Fisca is a Moroccan e-invoicing and accounting SaaS. Its principal product workflow is invoice handling through the API, with tenant-scoped access and accounting support; the repository also includes a POS client, SaaS interface, fiscal-rule engine, and public marketing site. The graph includes major subsystems visible in the tree and required core modules. Evidence is limited to the README, source index, and excerpts provided; dashed edges mark unverified product connections.

Main entry points: [`apps/api-hono/src/index.ts`](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/index.ts) (HTTP API), [`apps/api-hono/src/routes/invoices/invoices-routes.ts`](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/routes/invoices/invoices-routes.ts) (Invoice routes), [`apps/pos-pwa/src/sync/sync-engine.ts`](https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/sync/sync-engine.ts) (Offline sync), [`apps/api-hono/src/core/tenant-router.ts`](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/tenant-router.ts) (Tenant routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounting"]
  node_api["HTTP API<br/>[index.ts]"]
  node_tenant["Tenant routing<br/>[tenant-router.ts]"]
  node_pipeline["Request pipeline"]
  node_ledger["CGNC ledger"]
  node_ledgererrors["Ledger errors<br/>[ledger-errors.ts]"]
  node_schemas["API schemas<br/>[api-v1-schemas.ts]"]
  node_sql[("Durable SQL")]
  node_idempotency[("Idempotency store")]
end

subgraph group_invoice["Invoice compliance"]
  node_invoices["Invoice routes<br/>[invoices-routes.ts]"]
  node_sequencer[("Invoice sequencing")]
  node_clearance["DGI clearance<br/>[engine.ts]"]
  node_ubl["UBL signing<br/>[xades.ts]"]
  node_posapi["POS API<br/>[pos-routes.ts]"]
end

subgraph group_clients["Product clients"]
  node_posclient["POS client<br/>[index.ts]"]
  node_sync["Offline sync<br/>[sync-engine.ts]"]
  node_storage[("POS storage<br/>[ports.ts]")]
  node_web["SaaS interface<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth-2fa.ts]"]
end

subgraph group_fiscal["Fiscal services"]
  node_fiscal["Fiscal rule engine"]
  node_e2ee["Data encryption<br/>[e2ee-engine.ts]"]
end

subgraph group_public["Public site"]
  node_marketing["Marketing site<br/>[index.ts]"]
  node_content["Editorial content<br/>[pages.ts]"]
  node_seo["SEO handlers<br/>[handlers.ts]"]
end

node_user(("Business user"))

node_user -.->|"submits invoices"| node_api
node_api -.->|"routes requests"| node_tenant
node_api -.->|"dispatches invoice routes"| node_invoices
node_tenant -.->|"selects tenant context"| node_pipeline
node_invoices -.->|"allocates numbers"| node_sequencer
node_invoices -.->|"requests clearance"| node_clearance
node_clearance -.->|"processes signed invoices"| node_ubl
node_api -.->|"serves ledger operations"| node_ledger
node_ledger -->|"raises typed errors"| node_ledgererrors
node_api -.->|"validates API data"| node_schemas
node_invoices -.->|"deduplicates requests"| node_idempotency
node_posclient -.->|"stores local data"| node_storage
node_sync -->|"loads and updates"| node_storage
node_sync -.->|"sends batches"| node_posapi
node_web -.->|"calls API"| node_api
node_pipeline -.->|"applies access controls"| node_auth
node_marketing -.->|"serves SEO responses"| node_seo
node_seo -->|"reads editorial pages"| node_content
node_user -.->|"visits site"| node_marketing
node_api -.->|"uses fiscal calculations"| node_fiscal
node_api -.->|"protects tenant data"| node_e2ee

click node_api "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/index.ts"
click node_tenant "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/tenant-router.ts"
click node_pipeline "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/pipeline-composition.ts"
click node_ledger "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/immutable-cgnc-ledger-engine.ts"
click node_ledgererrors "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/ledger-errors.ts"
click node_schemas "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/api-v1-schemas.ts"
click node_sql "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/durable-object-sql.ts"
click node_idempotency "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/sql-idempotency-store.ts"
click node_invoices "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/routes/invoices/invoices-routes.ts"
click node_sequencer "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/invoice-sequencer-do.ts"
click node_clearance "https://github.com/anasse84/fisca/blob/main/packages/ubl-xades/src/clearance/engine.ts"
click node_ubl "https://github.com/anasse84/fisca/blob/main/packages/ubl-xades/src/signature/xades.ts"
click node_posapi "https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/routes/pos/pos-routes.ts"
click node_posclient "https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/index.ts"
click node_sync "https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/sync/sync-engine.ts"
click node_storage "https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/storage/ports.ts"
click node_web "https://github.com/anasse84/fisca/blob/main/apps/web-saas/src/index.ts"
click node_auth "https://github.com/anasse84/fisca/blob/main/packages/auth-rbac/src/auth-2fa.ts"
click node_fiscal "https://github.com/anasse84/fisca/blob/main/packages/fiscal-ast/src/dynamic-fiscal-ast-engine.ts"
click node_e2ee "https://github.com/anasse84/fisca/blob/main/packages/crypto-e2ee/src/e2ee-engine.ts"
click node_marketing "https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/index.ts"
click node_content "https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/content/pages.ts"
click node_seo "https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/seo/handlers.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_tenant,node_pipeline,node_ledger,node_ledgererrors,node_schemas,node_sql,node_idempotency,node_user toneBlue
class node_invoices,node_sequencer,node_clearance,node_ubl,node_posapi toneAmber
class node_posclient,node_sync,node_storage,node_web,node_auth toneMint
class node_fiscal,node_e2ee toneRose
class node_marketing,node_content,node_seo toneIndigo
```

## Components

### API and accounting

- [HTTP API](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/index.ts): `apps/api-hono/src/index.ts`
- [Tenant routing](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/tenant-router.ts): `apps/api-hono/src/core/tenant-router.ts`
- [Request pipeline](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/pipeline-composition.ts): `apps/api-hono/src/core/pipeline-composition.ts`
- [CGNC ledger](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/immutable-cgnc-ledger-engine.ts): `apps/api-hono/src/core/immutable-cgnc-ledger-engine.ts`
- [Ledger errors](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/ledger-errors.ts): `apps/api-hono/src/core/ledger-errors.ts`
- [API schemas](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/api-v1-schemas.ts): `apps/api-hono/src/core/api-v1-schemas.ts`
- [Durable SQL](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/durable-object-sql.ts): `apps/api-hono/src/core/durable-object-sql.ts`
- [Idempotency store](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/sql-idempotency-store.ts): `apps/api-hono/src/core/sql-idempotency-store.ts`

### Invoice compliance

- [Invoice routes](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/routes/invoices/invoices-routes.ts): `apps/api-hono/src/routes/invoices/invoices-routes.ts`
- [Invoice sequencing](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/core/invoice-sequencer-do.ts): `apps/api-hono/src/core/invoice-sequencer-do.ts`
- [DGI clearance](https://github.com/anasse84/fisca/blob/main/packages/ubl-xades/src/clearance/engine.ts): `packages/ubl-xades/src/clearance/engine.ts`
- [UBL signing](https://github.com/anasse84/fisca/blob/main/packages/ubl-xades/src/signature/xades.ts): `packages/ubl-xades/src/signature/xades.ts`
- [POS API](https://github.com/anasse84/fisca/blob/main/apps/api-hono/src/routes/pos/pos-routes.ts): `apps/api-hono/src/routes/pos/pos-routes.ts`

### Product clients

- [POS client](https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/index.ts): `apps/pos-pwa/src/index.ts`
- [Offline sync](https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/sync/sync-engine.ts): `apps/pos-pwa/src/sync/sync-engine.ts`
- [POS storage](https://github.com/anasse84/fisca/blob/main/apps/pos-pwa/src/storage/ports.ts): `apps/pos-pwa/src/storage/ports.ts`
- [SaaS interface](https://github.com/anasse84/fisca/blob/main/apps/web-saas/src/index.ts): `apps/web-saas/src/index.ts`
- [Authentication](https://github.com/anasse84/fisca/blob/main/packages/auth-rbac/src/auth-2fa.ts): `packages/auth-rbac/src/auth-2fa.ts`

### Fiscal services

- [Fiscal rule engine](https://github.com/anasse84/fisca/blob/main/packages/fiscal-ast/src/dynamic-fiscal-ast-engine.ts): `packages/fiscal-ast/src/dynamic-fiscal-ast-engine.ts`
- [Data encryption](https://github.com/anasse84/fisca/blob/main/packages/crypto-e2ee/src/e2ee-engine.ts): `packages/crypto-e2ee/src/e2ee-engine.ts`

### Public site

- [Marketing site](https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/index.ts): `apps/marketing-astro/src/index.ts`
- [Editorial content](https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/content/pages.ts): `apps/marketing-astro/src/content/pages.ts`
- [SEO handlers](https://github.com/anasse84/fisca/blob/main/apps/marketing-astro/src/seo/handlers.ts): `apps/marketing-astro/src/seo/handlers.ts`

### Other components

- **Business user**

## Connections

- Business user → HTTP API: submits invoices
- HTTP API → Tenant routing: routes requests
- HTTP API → Invoice routes: dispatches invoice routes
- Tenant routing → Request pipeline: selects tenant context
- Invoice routes → Invoice sequencing: allocates numbers
- Invoice routes → DGI clearance: requests clearance
- DGI clearance → UBL signing: processes signed invoices
- HTTP API → CGNC ledger: serves ledger operations
- CGNC ledger → Ledger errors: raises typed errors (evidence: `apps/api-hono/src/core/immutable-cgnc-ledger-engine.ts`)
- HTTP API → API schemas: validates API data
- Invoice routes → Idempotency store: deduplicates requests
- POS client → POS storage: stores local data
- Offline sync → POS storage: loads and updates (evidence: `apps/pos-pwa/src/sync/sync-engine.ts`)
- Offline sync → POS API: sends batches
- SaaS interface → HTTP API: calls API
- Request pipeline → Authentication: applies access controls
- Marketing site → SEO handlers: serves SEO responses
- SEO handlers → Editorial content: reads editorial pages (evidence: `apps/marketing-astro/src/seo/handlers.ts`)
- Business user → Marketing site: visits site
- HTTP API → Fiscal rule engine: uses fiscal calculations
- HTTP API → Data encryption: protects tenant data
