# guirrasup/sistemanex architecture

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

- Interactive diagram: https://gitdiagram.com/guirrasup/sistemanex
- Repository: https://github.com/guirrasup/sistemanex

## Overview

SistemaNEX is a Brazilian ERP and electronic-fiscal-document platform. The main user journey runs from the React application through its API services and Express routes/controllers to fiscal business services and persistent storage, then returns results for display and document viewing. Distinct product areas include authentication, registrations, finance and inventory, fiscal document issuance, tax calculations, and CNPJ lookup. The README documents the overall flow and capabilities; several backend integrations and feature internals are represented at their supported directory level because their source was not sampled.

Main entry points: [`src/App.tsx`](https://github.com/guirrasup/sistemanex/blob/main/src/App.tsx) (Application shell), [`backend/src/controllers`](https://github.com/guirrasup/sistemanex/tree/main/backend/src/controllers) (Fiscal controllers), [`backend/src/services`](https://github.com/guirrasup/sistemanex/tree/main/backend/src/services) (Fiscal workflows), [`src/services/api.ts`](https://github.com/guirrasup/sistemanex/blob/main/src/services/api.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_authui["Login<br/>[LoginView.tsx]"]
  node_fiscalui["Fiscal issuers"]
  node_doclist["Fiscal archive"]
  node_dashboard["Dashboard<br/>[DashboardReal.tsx]"]
  node_financeui["Finance screens<br/>[FinanceiroView.tsx]"]
  node_clientui["Customer records<br/>[ClientesView.tsx]"]
  node_cnpjui["CNPJ lookup"]
end

subgraph group_api["API application"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_fiscal_clients["Fiscal API services"]
  node_erp_clients["ERP API services"]
  node_server["Express server<br/>[server.ts]"]
  node_routes["REST routes"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_auth_mw["Session middleware<br/>[auth.middleware.ts]"]
  node_fiscal_ctrl["Fiscal controllers"]
end

subgraph group_fiscal["Fiscal operations"]
  node_fiscal_svc["Fiscal workflows"]
  node_xml_sign["XML and signing"]
  node_tax_engine["Tax calculation<br/>[tributosEngine.ts]"]
end

subgraph group_erp["ERP operations"]
  node_erp_svc["ERP workflows"]
end

subgraph group_data["Data and integrations"]
  node_repos["Repositories"]
  node_database[("Relational database<br/>[prisma.ts]")]
  node_local_storage[("Browser storage<br/>[storage.ts]")]
  node_email["Email service<br/>[email.service.ts]"]
  node_logger["Application logger<br/>[logger.ts]"]
end

node_user(("Business user"))
node_external["Tax authorities"]
node_cnpj_external["CNPJ providers"]

node_user -->|"uses"| node_app
node_app -->|"presents"| node_authui
node_app -->|"presents"| node_fiscalui
node_app -->|"presents"| node_doclist
node_app -->|"presents"| node_dashboard
node_app -.->|"presents"| node_financeui
node_app -.->|"presents"| node_clientui
node_app -->|"presents"| node_cnpjui
node_authui -->|"authenticates via"| node_api_client
node_fiscalui -->|"requests documents"| node_fiscal_clients
node_doclist -.->|"loads archive"| node_fiscal_clients
node_financeui -->|"requests finance"| node_erp_clients
node_clientui -->|"requests records"| node_erp_clients
node_cnpjui -.->|"looks up"| node_cnpj_external
node_fiscal_clients -->|"sends requests"| node_api_client
node_erp_clients -->|"sends requests"| node_api_client
node_api_client -->|"calls REST API"| node_server
node_server -->|"mounts routes"| node_routes
node_routes -->|"routes requests"| node_fiscal_ctrl
node_routes -->|"guards requests"| node_auth_mw
node_auth_mw -->|"validates session"| node_auth
node_fiscal_ctrl -->|"orchestrates"| node_fiscal_svc
node_fiscal_svc -.->|"generates signed XML"| node_xml_sign
node_fiscal_svc -.->|"calculates taxes"| node_tax_engine
node_fiscal_svc -.->|"submits documents"| node_external
node_fiscal_ctrl -.->|"uses ERP operations"| node_erp_svc
node_fiscal_ctrl -->|"sends notices"| node_email
node_erp_svc -.->|"uses repositories"| node_repos
node_fiscal_svc -.->|"uses repositories"| node_repos
node_repos -.->|"persists records"| node_database
node_app -->|"loads cached state"| node_local_storage
node_fiscal_ctrl -->|"logs activity"| node_logger
node_auth -->|"sends account email"| node_email

click node_app "https://github.com/guirrasup/sistemanex/blob/main/src/App.tsx"
click node_authui "https://github.com/guirrasup/sistemanex/blob/main/src/components/auth/LoginView.tsx"
click node_fiscalui "https://github.com/guirrasup/sistemanex/tree/main/src/components/fiscal"
click node_doclist "https://github.com/guirrasup/sistemanex/blob/main/src/components/fiscal/DocumentosFiscaisList.tsx"
click node_dashboard "https://github.com/guirrasup/sistemanex/blob/main/src/components/dashboard/DashboardReal.tsx"
click node_financeui "https://github.com/guirrasup/sistemanex/blob/main/src/components/financeiro/FinanceiroView.tsx"
click node_clientui "https://github.com/guirrasup/sistemanex/blob/main/src/components/cadastros/ClientesView.tsx"
click node_cnpjui "https://github.com/guirrasup/sistemanex/blob/main/src/components/tools/ConsultaCnpjView.tsx"
click node_api_client "https://github.com/guirrasup/sistemanex/blob/main/src/services/api.ts"
click node_fiscal_clients "https://github.com/guirrasup/sistemanex/tree/main/src/services"
click node_erp_clients "https://github.com/guirrasup/sistemanex/tree/main/src/services"
click node_server "https://github.com/guirrasup/sistemanex/blob/main/backend/src/server.ts"
click node_routes "https://github.com/guirrasup/sistemanex/tree/main/backend/src/routes"
click node_auth "https://github.com/guirrasup/sistemanex/blob/main/backend/src/services/auth.service.ts"
click node_auth_mw "https://github.com/guirrasup/sistemanex/blob/main/backend/src/middlewares/auth.middleware.ts"
click node_fiscal_ctrl "https://github.com/guirrasup/sistemanex/tree/main/backend/src/controllers"
click node_fiscal_svc "https://github.com/guirrasup/sistemanex/tree/main/backend/src/services"
click node_xml_sign "https://github.com/guirrasup/sistemanex/tree/main/backend/src/utils"
click node_tax_engine "https://github.com/guirrasup/sistemanex/blob/main/backend/src/utils/tributosEngine.ts"
click node_erp_svc "https://github.com/guirrasup/sistemanex/tree/main/backend/src/services"
click node_repos "https://github.com/guirrasup/sistemanex/tree/main/backend/src/repositories"
click node_database "https://github.com/guirrasup/sistemanex/blob/main/backend/src/lib/prisma.ts"
click node_local_storage "https://github.com/guirrasup/sistemanex/blob/main/src/utils/storage.ts"
click node_email "https://github.com/guirrasup/sistemanex/blob/main/backend/src/services/email.service.ts"
click node_logger "https://github.com/guirrasup/sistemanex/blob/main/backend/src/lib/logger.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_app,node_authui,node_fiscalui,node_doclist,node_dashboard,node_financeui,node_clientui,node_cnpjui,node_user toneBlue
class node_api_client,node_fiscal_clients,node_erp_clients,node_server,node_routes,node_auth,node_auth_mw,node_fiscal_ctrl toneAmber
class node_fiscal_svc,node_xml_sign,node_tax_engine toneMint
class node_erp_svc toneRose
class node_repos,node_database,node_local_storage,node_email,node_logger,node_external,node_cnpj_external toneIndigo
```

## Components

### User interface

- [Application shell](https://github.com/guirrasup/sistemanex/blob/main/src/App.tsx): `src/App.tsx`
- [Login](https://github.com/guirrasup/sistemanex/blob/main/src/components/auth/LoginView.tsx): `src/components/auth/LoginView.tsx`
- [Fiscal issuers](https://github.com/guirrasup/sistemanex/tree/main/src/components/fiscal): `src/components/fiscal`
- [Fiscal archive](https://github.com/guirrasup/sistemanex/blob/main/src/components/fiscal/DocumentosFiscaisList.tsx): `src/components/fiscal/DocumentosFiscaisList.tsx`
- [Dashboard](https://github.com/guirrasup/sistemanex/blob/main/src/components/dashboard/DashboardReal.tsx): `src/components/dashboard/DashboardReal.tsx`
- [Finance screens](https://github.com/guirrasup/sistemanex/blob/main/src/components/financeiro/FinanceiroView.tsx): `src/components/financeiro/FinanceiroView.tsx`
- [Customer records](https://github.com/guirrasup/sistemanex/blob/main/src/components/cadastros/ClientesView.tsx): `src/components/cadastros/ClientesView.tsx`
- [CNPJ lookup](https://github.com/guirrasup/sistemanex/blob/main/src/components/tools/ConsultaCnpjView.tsx): `src/components/tools/ConsultaCnpjView.tsx`

### API application

- [HTTP client](https://github.com/guirrasup/sistemanex/blob/main/src/services/api.ts): `src/services/api.ts`
- [Fiscal API services](https://github.com/guirrasup/sistemanex/tree/main/src/services): `src/services`
- [ERP API services](https://github.com/guirrasup/sistemanex/tree/main/src/services): `src/services`
- [Express server](https://github.com/guirrasup/sistemanex/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [REST routes](https://github.com/guirrasup/sistemanex/tree/main/backend/src/routes): `backend/src/routes`
- [Authentication](https://github.com/guirrasup/sistemanex/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Session middleware](https://github.com/guirrasup/sistemanex/blob/main/backend/src/middlewares/auth.middleware.ts): `backend/src/middlewares/auth.middleware.ts`
- [Fiscal controllers](https://github.com/guirrasup/sistemanex/tree/main/backend/src/controllers): `backend/src/controllers`

### Fiscal operations

- [Fiscal workflows](https://github.com/guirrasup/sistemanex/tree/main/backend/src/services): `backend/src/services`
- [XML and signing](https://github.com/guirrasup/sistemanex/tree/main/backend/src/utils): `backend/src/utils`
- [Tax calculation](https://github.com/guirrasup/sistemanex/blob/main/backend/src/utils/tributosEngine.ts): `backend/src/utils/tributosEngine.ts`

### ERP operations

- [ERP workflows](https://github.com/guirrasup/sistemanex/tree/main/backend/src/services): `backend/src/services`

### Data and integrations

- [Repositories](https://github.com/guirrasup/sistemanex/tree/main/backend/src/repositories): `backend/src/repositories`
- [Relational database](https://github.com/guirrasup/sistemanex/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`
- [Browser storage](https://github.com/guirrasup/sistemanex/blob/main/src/utils/storage.ts): `src/utils/storage.ts`
- [Email service](https://github.com/guirrasup/sistemanex/blob/main/backend/src/services/email.service.ts): `backend/src/services/email.service.ts`
- [Application logger](https://github.com/guirrasup/sistemanex/blob/main/backend/src/lib/logger.ts): `backend/src/lib/logger.ts`

### Other components

- **Business user**
- **Tax authorities**
- **CNPJ providers**

## Connections

- Business user → Application shell: uses (evidence: `README.md`)
- Application shell → Login: presents (evidence: `src/App.tsx`)
- Application shell → Fiscal issuers: presents (evidence: `src/App.tsx`)
- Application shell → Fiscal archive: presents (evidence: `src/App.tsx`)
- Application shell → Dashboard: presents (evidence: `src/App.tsx`)
- Application shell → Finance screens: presents (evidence: `src/App.tsx`)
- Application shell → Customer records: presents (evidence: `src/App.tsx`)
- Application shell → CNPJ lookup: presents (evidence: `src/App.tsx`)
- Login → HTTP client: authenticates via (evidence: `src/components/auth/LoginView.tsx`)
- Fiscal issuers → Fiscal API services: requests documents (evidence: `src/components/fiscal/CteEmissor.tsx`)
- Fiscal archive → Fiscal API services: loads archive
- Finance screens → ERP API services: requests finance (evidence: `src/components/financeiro/FinanceiroView.tsx`)
- Customer records → ERP API services: requests records (evidence: `src/components/cadastros/ClientesView.tsx`)
- CNPJ lookup → CNPJ providers: looks up
- Fiscal API services → HTTP client: sends requests (evidence: `src/services/cte.service.ts`)
- ERP API services → HTTP client: sends requests (evidence: `src/services/clientes.service.ts`)
- HTTP client → Express server: calls REST API (evidence: `README.md`)
- Express server → REST routes: mounts routes (evidence: `backend/src/server.ts`)
- REST routes → Fiscal controllers: routes requests (evidence: `backend/src/routes/nfe.routes.ts`)
- REST routes → Session middleware: guards requests (evidence: `backend/src/routes/nfe.routes.ts`)
- Session middleware → Authentication: validates session (evidence: `backend/src/middlewares/auth.middleware.ts`)
- Fiscal controllers → Fiscal workflows: orchestrates (evidence: `backend/src/controllers/nfe.controller.ts`)
- Fiscal workflows → XML and signing: generates signed XML
- Fiscal workflows → Tax calculation: calculates taxes
- Fiscal workflows → Tax authorities: submits documents (evidence: `README.md`)
- Fiscal controllers → ERP workflows: uses ERP operations (evidence: `backend/src/controllers/cte.controller.ts`)
- Fiscal controllers → Email service: sends notices (evidence: `backend/src/controllers/nfe.controller.ts`)
- ERP workflows → Repositories: uses repositories (evidence: `backend/src/services/auth.service.ts`)
- Fiscal workflows → Repositories: uses repositories (evidence: `backend/src/services/auth.service.ts`)
- Repositories → Relational database: persists records (evidence: `README.md`)
- Application shell → Browser storage: loads cached state (evidence: `src/App.tsx`)
- Fiscal controllers → Application logger: logs activity (evidence: `backend/src/controllers/nfe.controller.ts`)
- Authentication → Email service: sends account email (evidence: `backend/src/services/auth.service.ts`)
