# landertz507/cuentaclara architecture

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

- Interactive diagram: https://gitdiagram.com/landertz507/cuentaclara
- Repository: https://github.com/landertz507/cuentaclara

## Overview

CuentaClara is a multi-tenant ERP mobile app for small businesses, with quick/simple and structured/advanced operating modes. Users authenticate, enter a mode-specific dashboard, and manage sales, inventory, cash, billing, and related operations through a React Native client and FastAPI business API backed by Supabase. Authentication combines Supabase sessions with API-loaded business profiles. The README also describes push notifications and WhatsApp integrations; those links are documented, but their implementation is not shown in the sampled source.

Main entry points: [`App.js`](https://github.com/landertz507/cuentaclara/blob/main/App.js) (App shell), [`backend/app/main.py`](https://github.com/landertz507/cuentaclara/blob/main/backend/app/main.py) (FastAPI gateway), [`src/modules/auth/hooks/useAuth.js`](https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/hooks/useAuth.js) (Authentication flow), [`src/modules/auth/services/authService.js`](https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/services/authService.js) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_app["App shell<br/>[App.js]"]
  node_navigation["Mode navigation"]
  node_auth_flow["Authentication flow<br/>[useAuth.js]"]
  node_auth_client["Auth service<br/>[authService.js]"]
  node_session_store["Session state<br/>[useAuthStore.js]"]
  node_api_client["API client<br/>[apiClient.js]"]
end

subgraph group_operations["Business operations"]
  node_dashboard["Dashboard engine<br/>[dashboardEngine.js]"]
  node_inventory_ui["Inventory workflows"]
  node_sales_ui["Sales and cash"]
  node_billing_ui["Billing and invoices"]
  node_analytics["Strategic analytics"]
  node_other_modules["Other ERP modules"]
end

subgraph group_backend["Backend API"]
  node_api["FastAPI gateway<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_domain_routes["Business routes"]
  node_auth_service["Auth logic<br/>[auth_service.py]"]
  node_inventory_service["Inventory logic"]
  node_recipe_service["Recipe production<br/>[recipes_service.py]"]
end

subgraph group_data["Identity and data"]
  node_database_client["Supabase clients<br/>[database.py]"]
end

node_user(("Business user"))
node_supabase[("Supabase")]
node_push_service["Firebase messaging"]
node_whatsapp["WhatsApp API"]

node_user -->|"opens"| node_app
node_app -->|"mounts"| node_navigation
node_app -.->|"provides auth"| node_auth_flow
node_navigation -.->|"routes"| node_auth_flow
node_auth_flow -->|"calls"| node_auth_client
node_auth_flow -->|"updates"| node_session_store
node_auth_client -->|"authenticates"| node_supabase
node_auth_client -->|"loads profile"| node_api_client
node_app -->|"initializes"| node_supabase
node_app -.->|"enters operations"| node_dashboard
node_dashboard -.->|"presents summaries"| node_user
node_user -.->|"manages stock"| node_inventory_ui
node_user -.->|"records sales"| node_sales_ui
node_user -.->|"creates invoices"| node_billing_ui
node_user -.->|"reviews reports"| node_analytics
node_user -.->|"manages operations"| node_other_modules
node_inventory_ui -->|"requests data"| node_api_client
node_api_client -->|"sends requests"| node_api
node_api -->|"registers routes"| node_auth_routes
node_api -->|"registers routes"| node_domain_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_service -->|"uses clients"| node_database_client
node_database_client -->|"connects"| node_supabase
node_inventory_service -->|"uses clients"| node_database_client
node_recipe_service -->|"uses inventory"| node_inventory_service
node_inventory_service -.->|"dispatches alerts"| node_push_service
node_api -.->|"supports push"| node_push_service
node_api -.->|"supports messaging"| node_whatsapp

click node_app "https://github.com/landertz507/cuentaclara/blob/main/App.js"
click node_navigation "https://github.com/landertz507/cuentaclara/tree/main/src/views/navigation"
click node_auth_flow "https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/hooks/useAuth.js"
click node_auth_client "https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/services/authService.js"
click node_session_store "https://github.com/landertz507/cuentaclara/blob/main/src/store/useAuthStore.js"
click node_api_client "https://github.com/landertz507/cuentaclara/blob/main/src/services/apiClient.js"
click node_dashboard "https://github.com/landertz507/cuentaclara/blob/main/src/modules/dashboard/engine/dashboardEngine.js"
click node_inventory_ui "https://github.com/landertz507/cuentaclara/tree/main/src/modules/inventory"
click node_sales_ui "https://github.com/landertz507/cuentaclara/tree/main/src/modules/sales"
click node_billing_ui "https://github.com/landertz507/cuentaclara/tree/main/src/modules/Invoice"
click node_analytics "https://github.com/landertz507/cuentaclara/tree/main/src/modules/analytics"
click node_other_modules "https://github.com/landertz507/cuentaclara/tree/main/src/modules"
click node_api "https://github.com/landertz507/cuentaclara/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/landertz507/cuentaclara/blob/main/backend/app/routers/auth.py"
click node_domain_routes "https://github.com/landertz507/cuentaclara/tree/main/backend/app/routers"
click node_auth_service "https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/auth_service.py"
click node_inventory_service "https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/inventory_service.py"
click node_recipe_service "https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/recipes_service.py"
click node_database_client "https://github.com/landertz507/cuentaclara/blob/main/backend/app/database.py"

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_navigation,node_auth_flow,node_auth_client,node_session_store,node_api_client,node_user toneBlue
class node_dashboard,node_inventory_ui,node_sales_ui,node_billing_ui,node_analytics,node_other_modules,node_supabase toneAmber
class node_api,node_auth_routes,node_domain_routes,node_auth_service,node_inventory_service,node_recipe_service,node_whatsapp toneMint
class node_database_client toneRose
class node_push_service toneIndigo
```

## Components

### Mobile app

- [App shell](https://github.com/landertz507/cuentaclara/blob/main/App.js): `App.js`
- [Mode navigation](https://github.com/landertz507/cuentaclara/tree/main/src/views/navigation): `src/views/navigation`
- [Authentication flow](https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/hooks/useAuth.js): `src/modules/auth/hooks/useAuth.js`
- [Auth service](https://github.com/landertz507/cuentaclara/blob/main/src/modules/auth/services/authService.js): `src/modules/auth/services/authService.js`
- [Session state](https://github.com/landertz507/cuentaclara/blob/main/src/store/useAuthStore.js): `src/store/useAuthStore.js`
- [API client](https://github.com/landertz507/cuentaclara/blob/main/src/services/apiClient.js): `src/services/apiClient.js`

### Business operations

- [Dashboard engine](https://github.com/landertz507/cuentaclara/blob/main/src/modules/dashboard/engine/dashboardEngine.js): `src/modules/dashboard/engine/dashboardEngine.js`
- [Inventory workflows](https://github.com/landertz507/cuentaclara/tree/main/src/modules/inventory): `src/modules/inventory`
- [Sales and cash](https://github.com/landertz507/cuentaclara/tree/main/src/modules/sales): `src/modules/sales`
- [Billing and invoices](https://github.com/landertz507/cuentaclara/tree/main/src/modules/Invoice): `src/modules/Invoice`
- [Strategic analytics](https://github.com/landertz507/cuentaclara/tree/main/src/modules/analytics): `src/modules/analytics`
- [Other ERP modules](https://github.com/landertz507/cuentaclara/tree/main/src/modules): `src/modules`

### Backend API

- [FastAPI gateway](https://github.com/landertz507/cuentaclara/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/landertz507/cuentaclara/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Business routes](https://github.com/landertz507/cuentaclara/tree/main/backend/app/routers): `backend/app/routers`
- [Auth logic](https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Inventory logic](https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/inventory_service.py): `backend/app/services/inventory_service.py`
- [Recipe production](https://github.com/landertz507/cuentaclara/blob/main/backend/app/services/recipes_service.py): `backend/app/services/recipes_service.py`

### Identity and data

- [Supabase clients](https://github.com/landertz507/cuentaclara/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Business user**
- **Supabase**
- **Firebase messaging**
- **WhatsApp API**

## Connections

- Business user → App shell: opens (evidence: `README.md`)
- App shell → Mode navigation: mounts (evidence: `App.js`)
- App shell → Authentication flow: provides auth
- Mode navigation → Authentication flow: routes
- Authentication flow → Auth service: calls (evidence: `src/modules/auth/hooks/useAuth.js`)
- Authentication flow → Session state: updates (evidence: `src/modules/auth/hooks/useAuth.js`)
- Auth service → Supabase: authenticates (evidence: `src/modules/auth/services/authService.js`)
- Auth service → API client: loads profile (evidence: `src/modules/auth/services/authService.js`)
- App shell → Supabase: initializes (evidence: `App.js`)
- App shell → Dashboard engine: enters operations
- Dashboard engine → Business user: presents summaries
- Business user → Inventory workflows: manages stock (evidence: `README.md`)
- Business user → Sales and cash: records sales (evidence: `README.md`)
- Business user → Billing and invoices: creates invoices (evidence: `README.md`)
- Business user → Strategic analytics: reviews reports (evidence: `README.md`)
- Business user → Other ERP modules: manages operations
- Inventory workflows → API client: requests data (evidence: `src/modules/inventory/services/inventoryService.js`)
- API client → FastAPI gateway: sends requests (evidence: `README.md`)
- FastAPI gateway → Auth routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI gateway → Business routes: registers routes (evidence: `backend/app/main.py`)
- Auth routes → Auth logic: calls (evidence: `backend/app/routers/auth.py`)
- Auth logic → Supabase clients: uses clients (evidence: `backend/app/services/auth_service.py`)
- Supabase clients → Supabase: connects (evidence: `backend/app/database.py`)
- Inventory logic → Supabase clients: uses clients (evidence: `backend/app/services/inventory_service.py`)
- Recipe production → Inventory logic: uses inventory (evidence: `backend/app/services/recipes_service.py`)
- Inventory logic → Firebase messaging: dispatches alerts
- FastAPI gateway → Firebase messaging: supports push (evidence: `README.md`)
- FastAPI gateway → WhatsApp API: supports messaging (evidence: `README.md`)
