# miphu2804/smart-ledger architecture

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

- Interactive diagram: https://gitdiagram.com/miphu2804/smart-ledger
- Repository: https://github.com/miphu2804/smart-ledger

## Overview

SmartLedger is an MVP for shop owners using a mobile app, with a separate admin web console and backend services. The owner flow is Firebase sign-in, Core session creation, optional shop onboarding, then shop workflows; mobile currently defaults to mock data, and shop/ledger APIs are not implemented. The admin console covers dashboards, customers, AI support, tasks, and settings, also mock-first. AI provides internal agent chat and persistent conversations, but Core does not call it. Some screens and integrations are represented from the tree and README rather than inspected implementation.

Main entry points: [`frontend/mobile/src/store/AppStore.tsx`](https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/store/AppStore.tsx) (App state), [`backend/ai/src/main.py`](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/main.py) (AI application setup), [`frontend/mobile/app`](https://github.com/miphu2804/smart-ledger/tree/main/frontend/mobile/app) (Owner workflows), [`frontend/web/src/App.tsx`](https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/App.tsx) (Admin routes and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Owner mobile"]
  node_mobile_auth["Sign-in screens"]
  node_mobile_session["Session and onboarding<br/>[sessionApi.ts]"]
  node_mobile_state["App state<br/>[AppStore.tsx]"]
  node_mobile_home["Owner workflows"]
  node_mobile_reports["Reports and stats<br/>[useReport.ts]"]
  node_mobile_mock[("Mock shop data<br/>[mock.ts]")]
end

subgraph group_web["Admin web"]
  node_web_admin["Admin routes and pages<br/>[App.tsx]"]
  node_web_tasks["Task management<br/>[TasksPage.tsx]"]
  node_web_task_service["Task service<br/>[taskService.ts]"]
  node_web_services["Admin data services"]
end

subgraph group_core["Core API"]
  node_core_auth["Session endpoint"]
  node_core_service["Session service"]
  node_core_identity[("Identity and shop records")]
end

subgraph group_ai["AI service"]
  node_ai_routes["Agent routes<br/>[routers.py]"]
  node_ai_service["Agent orchestration<br/>[service.py]"]
  node_ai_repo["Conversation repository<br/>[repository.py]"]
  node_ai_tools["Agent tools<br/>[tools.py]"]
  node_ai_model["Chat model provider<br/>[factory.py]"]
  node_ai_main["AI application setup<br/>[main.py]"]
end

subgraph group_infra["Persistence"]
  node_postgres_client["Postgres client"]
  node_postgres[("PostgreSQL")]
  node_redis_client["Redis client<br/>[redis_db_client.py]"]
  node_redis[("Redis")]
end

node_owner(("Shop owner"))
node_firebase["Firebase identity"]

node_owner -->|"signs in"| node_mobile_auth
node_mobile_auth -.->|"updates session"| node_mobile_state
node_mobile_state -->|"creates session"| node_mobile_session
node_mobile_session -->|"requests session"| node_core_auth
node_core_auth -->|"opens session"| node_core_service
node_core_service -->|"reads and writes"| node_core_identity
node_firebase -.->|"verifies identity"| node_core_auth
node_mobile_state -->|"loads mock state"| node_mobile_mock
node_mobile_state -.->|"serves workflows"| node_mobile_home
node_mobile_home -->|"requests report"| node_mobile_reports
node_mobile_reports -->|"reads shop data"| node_mobile_state
node_mobile_home -->|"uses sample flows"| node_mobile_mock
node_owner -.->|"administers platform"| node_web_admin
node_web_admin -->|"routes to tasks"| node_web_tasks
node_web_tasks -->|"loads and updates"| node_web_task_service
node_web_admin -.->|"routes admin areas"| node_web_services
node_ai_main -->|"registers routes"| node_ai_routes
node_ai_routes -->|"dispatches requests"| node_ai_service
node_ai_service -->|"loads and saves chats"| node_ai_repo
node_ai_service -->|"builds agent tools"| node_ai_tools
node_ai_main -->|"builds model"| node_ai_model
node_ai_main -->|"connects at startup"| node_postgres_client
node_ai_main -->|"connects at startup"| node_redis_client
node_ai_repo -->|"runs transactions"| node_postgres_client
node_postgres_client -->|"persists conversations"| node_postgres
node_redis_client -.->|"connects"| node_redis

click node_mobile_auth "https://github.com/miphu2804/smart-ledger/tree/main/frontend/mobile/app/(auth)"
click node_mobile_session "https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/lib/sessionApi.ts"
click node_mobile_state "https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/store/AppStore.tsx"
click node_mobile_home "https://github.com/miphu2804/smart-ledger/tree/main/frontend/mobile/app"
click node_mobile_reports "https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/lib/useReport.ts"
click node_mobile_mock "https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/data/mock.ts"
click node_core_auth "https://github.com/miphu2804/smart-ledger/blob/main/backend/core/src/main/java/com/smartledger/core/controller/AuthController.java"
click node_core_service "https://github.com/miphu2804/smart-ledger/blob/main/backend/core/src/main/java/com/smartledger/core/service/AuthSessionService.java"
click node_core_identity "https://github.com/miphu2804/smart-ledger/tree/main/backend/core/src/main/java/com/smartledger/core/entity"
click node_web_admin "https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/App.tsx"
click node_web_tasks "https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/pages/admin/TasksPage.tsx"
click node_web_task_service "https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/services/taskService.ts"
click node_web_services "https://github.com/miphu2804/smart-ledger/tree/main/frontend/web/src/services"
click node_ai_routes "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/routers.py"
click node_ai_service "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/service.py"
click node_ai_repo "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/repository.py"
click node_ai_tools "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/tools.py"
click node_ai_model "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/providers/factory.py"
click node_postgres_client "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/infra/postgre_db_client.py"
click node_redis_client "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/infra/redis_db_client.py"
click node_ai_main "https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/main.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_mobile_auth,node_mobile_session,node_mobile_state,node_mobile_home,node_mobile_reports,node_mobile_mock toneBlue
class node_web_admin,node_web_tasks,node_web_task_service,node_web_services toneAmber
class node_core_auth,node_core_service,node_core_identity toneMint
class node_ai_routes,node_ai_service,node_ai_repo,node_ai_tools,node_ai_model,node_ai_main toneRose
class node_postgres_client,node_postgres,node_redis_client,node_redis,node_owner,node_firebase toneIndigo
```

## Components

### Owner mobile

- [Sign-in screens](https://github.com/miphu2804/smart-ledger/tree/main/frontend/mobile/app/(auth)): `frontend/mobile/app/(auth)`
- [Session and onboarding](https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/lib/sessionApi.ts): `frontend/mobile/src/lib/sessionApi.ts`
- [App state](https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/store/AppStore.tsx): `frontend/mobile/src/store/AppStore.tsx`
- [Owner workflows](https://github.com/miphu2804/smart-ledger/tree/main/frontend/mobile/app): `frontend/mobile/app`
- [Reports and stats](https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/lib/useReport.ts): `frontend/mobile/src/lib/useReport.ts`
- [Mock shop data](https://github.com/miphu2804/smart-ledger/blob/main/frontend/mobile/src/data/mock.ts): `frontend/mobile/src/data/mock.ts`

### Admin web

- [Admin routes and pages](https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/App.tsx): `frontend/web/src/App.tsx`
- [Task management](https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/pages/admin/TasksPage.tsx): `frontend/web/src/pages/admin/TasksPage.tsx`
- [Task service](https://github.com/miphu2804/smart-ledger/blob/main/frontend/web/src/services/taskService.ts): `frontend/web/src/services/taskService.ts`
- [Admin data services](https://github.com/miphu2804/smart-ledger/tree/main/frontend/web/src/services): `frontend/web/src/services`

### Core API

- [Session endpoint](https://github.com/miphu2804/smart-ledger/blob/main/backend/core/src/main/java/com/smartledger/core/controller/AuthController.java): `backend/core/src/main/java/com/smartledger/core/controller/AuthController.java`
- [Session service](https://github.com/miphu2804/smart-ledger/blob/main/backend/core/src/main/java/com/smartledger/core/service/AuthSessionService.java): `backend/core/src/main/java/com/smartledger/core/service/AuthSessionService.java`
- [Identity and shop records](https://github.com/miphu2804/smart-ledger/tree/main/backend/core/src/main/java/com/smartledger/core/entity): `backend/core/src/main/java/com/smartledger/core/entity`

### AI service

- [Agent routes](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/routers.py): `backend/ai/src/agent/routers.py`
- [Agent orchestration](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/service.py): `backend/ai/src/agent/service.py`
- [Conversation repository](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/repository.py): `backend/ai/src/agent/repository.py`
- [Agent tools](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/agent/tools.py): `backend/ai/src/agent/tools.py`
- [Chat model provider](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/providers/factory.py): `backend/ai/src/providers/factory.py`
- [AI application setup](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/main.py): `backend/ai/src/main.py`

### Persistence

- [Postgres client](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/infra/postgre_db_client.py): `backend/ai/src/infra/postgre_db_client.py`
- **PostgreSQL**
- [Redis client](https://github.com/miphu2804/smart-ledger/blob/main/backend/ai/src/infra/redis_db_client.py): `backend/ai/src/infra/redis_db_client.py`
- **Redis**

### Other components

- **Shop owner**
- **Firebase identity**

## Connections

- Shop owner → Sign-in screens: signs in (evidence: `README.md`)
- Sign-in screens → App state: updates session
- App state → Session and onboarding: creates session (evidence: `frontend/mobile/src/store/AppStore.tsx`)
- Session and onboarding → Session endpoint: requests session (evidence: `frontend/mobile/src/lib/sessionApi.ts`)
- Session endpoint → Session service: opens session (evidence: `backend/core/src/main/java/com/smartledger/core/controller/AuthController.java`)
- Session service → Identity and shop records: reads and writes (evidence: `backend/core/src/main/java/com/smartledger/core/service/AuthSessionService.java`)
- Firebase identity → Session endpoint: verifies identity
- App state → Mock shop data: loads mock state (evidence: `frontend/mobile/src/store/AppStore.tsx`)
- App state → Owner workflows: serves workflows (evidence: `frontend/mobile/app/(tabs)/index.tsx`)
- Owner workflows → Reports and stats: requests report (evidence: `frontend/mobile/app/(tabs)/index.tsx`)
- Reports and stats → App state: reads shop data (evidence: `frontend/mobile/src/lib/useReport.ts`)
- Owner workflows → Mock shop data: uses sample flows (evidence: `frontend/mobile/app/voice.tsx`)
- Shop owner → Admin routes and pages: administers platform
- Admin routes and pages → Task management: routes to tasks (evidence: `frontend/web/src/App.tsx`)
- Task management → Task service: loads and updates (evidence: `frontend/web/src/pages/admin/TasksPage.tsx`)
- Admin routes and pages → Admin data services: routes admin areas
- AI application setup → Agent routes: registers routes (evidence: `backend/ai/src/main.py`)
- Agent routes → Agent orchestration: dispatches requests (evidence: `backend/ai/src/agent/routers.py`)
- Agent orchestration → Conversation repository: loads and saves chats (evidence: `backend/ai/src/agent/service.py`)
- Agent orchestration → Agent tools: builds agent tools (evidence: `backend/ai/src/agent/service.py`)
- AI application setup → Chat model provider: builds model (evidence: `backend/ai/src/main.py`)
- AI application setup → Postgres client: connects at startup (evidence: `backend/ai/src/main.py`)
- AI application setup → Redis client: connects at startup (evidence: `backend/ai/src/main.py`)
- Conversation repository → Postgres client: runs transactions (evidence: `backend/ai/src/agent/repository.py`)
- Postgres client → PostgreSQL: persists conversations
- Redis client → Redis: connects