# piriyalapa/project-lumine architecture

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

- Interactive diagram: https://gitdiagram.com/piriyalapa/project-lumine
- Repository: https://github.com/piriyalapa/project-lumine

## Overview

#### Purpose and Entry Points
Project Lumine is an evidence-based luxury-retail CRM centered on automated “2-2-2” customer follow-up. The API contract is authoritative at `openapi.yaml`. Backend startup is the FastAPI application in `backend/app/main.py`; the mobile entry point is the Expo React Native app at `mobile/App.tsx`.

#### Client Application
The mobile client provides authenticated workflows for dashboards, tasks, customers, evidence, uploads, and auto-touch follow-up. Navigation and screen composition are rooted in `mobile/src/navigation/AppNavigator.tsx`, with API/JWT handling in `mobile/src/api/client.ts`. It supports an offline-facing UI/cache boundary through `mobile/src/cache/offlineCache.ts` and `mobile/src/components/OfflineBanner.tsx`; a DEV_MODE mock path exists in `mobile/src/mock/mockData.ts`.

#### API and Authorization Boundary
FastAPI routers expose domain endpoints for auth, customers, tasks, evidence, uploads, reporting, stores, and auto-touch: `backend/app/routers/auth.py`, `backend/app/routers/tasks.py`, and `backend/app/routers/auto_touch.py`. JWT authentication is enforced at the middleware boundary in `backend/app/middleware/auth.py`, with credential/token business logic in `backend/app/services/auth_service.py`. Mobile requests cross this boundary via the shared Axios client.

#### Persistence Architecture
SQLAlchemy models define the CRM’s durable entities: customer, staff, store, transaction, follow-up task, message, evidence, and upload-log records under `backend/app/models/`. Repository modules isolate database queries from services, notably `backend/app/repositories/customer_repo.py`, `backend/app/repositories/task_repo.py`, and `backend/app/repositories/transaction_repo.py`. Database configuration/session setup is centralized in `backend/app/database.py`; Alembic migrations establish the MySQL schema in `backend/alembic/versions/`.

#### Customer and Task Automation
Customer registration/profile logic combines customer, transaction, and task state in `backend/app/services/customer_register_service.py` and `backend/app/services/customer_profile_service.py`. The 2-2-2 follow-up process is implemented by the scheduling and auto-touch layers: `backend/app/services/task_scheduler.py`, `backend/app/services/auto_touch_service.py`, and `backend/app/services/cycle_reset.py`. These services generate/manage follow-up tasks and message-related touchpoints, exposed through task and auto-touch routers.

#### Import, Evidence, and External Delivery
Upload processing ingests CRM/SAP-oriented data through `backend/app/routers/upload.py`, `backend/app/services/crm_import_service.py`, and `backend/app/services/sap_parser.py`; source-column normalization is externally defined in `backend/config/sap_column_map.json`. Evidence handling is a separate domain flow via `backend/app/services/evidence_service.py` and `backend/app/routers/evidence.py`. Google Drive is the evidence/file storage integration (`backend/app/services/google_drive_client.py`), while LINE and SMTP adapters deliver generated customer communications (`backend/app/services/line_client.py`, `backend/app/services/smtp_client.py`).

#### Reporting and Runtime Infrastructure
Dashboard and report aggregation flows through `backend/app/services/dashboard_service.py`, `backend/app/services/report_service.py`, and their repository layer. The backend runs as Python/FastAPI with SQLAlchemy and MySQL; Docker deployment is defined by `backend/Dockerfile` and `docker-compose.yml`. The mobile runtime is Expo/React Native TypeScript, configured from `mobile/package.json` and `mobile/app.json`.

Main entry points: [`backend/app/repositories/customer_repo.py`](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/repositories/customer_repo.py) (Repositories), [`backend/app/main.py`](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/main.py) (FastAPI Application), [`mobile/src/api/client.ts`](https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/api/client.ts) (API + JWT Client), [`backend/app/routers/auto_touch.py`](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/routers/auto_touch.py) (Task + Auto-touch API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile Client"]
  node_mobile_app["Expo App<br/>React Native entry<br/>[App.tsx]"]
  node_navigation["App Navigation<br/>screen composition<br/>[AppNavigator.tsx]"]
  node_api_client["API + JWT Client<br/>Axios client<br/>[client.ts]"]
  node_offline_cache["Offline UI Cache<br/>cache boundary<br/>[offlineCache.ts]"]
end

subgraph group_api["Backend API"]
  node_contract["OpenAPI Contract<br/>API specification<br/>[openapi.yaml]"]
  node_fastapi["FastAPI Application<br/>backend entry<br/>[main.py]"]
  node_auth_boundary["JWT Auth Middleware<br/>authorization boundary<br/>[auth.py]"]
  node_auth_service["Auth Service<br/>credential service<br/>[auth_service.py]"]
  node_domain_routers["Task + Auto-touch API<br/>domain routers<br/>[auto_touch.py]"]
  node_upload_evidence_api["Upload + Evidence API<br/>domain routers<br/>[upload.py]"]
end

subgraph group_domain["CRM Automation"]
  node_customer_services["Customer Lifecycle<br/>profile services"]
  node_automation["2-2-2 Automation<br/>scheduler services<br/>[task_scheduler.py]"]
  node_import_pipeline["CRM/SAP Import<br/>ingestion service"]
  node_evidence_service["Evidence Service<br/>evidence domain"]
  node_reporting["Dashboard + Reports<br/>aggregation service"]
end

subgraph group_data["Persistence"]
  node_repositories["Repositories<br/>data access layer<br/>[customer_repo.py]"]
  node_database["SQLAlchemy Session<br/>database setup<br/>[database.py]"]
  node_mysql_schema[("MySQL CRM Schema<br/>durable entities")]
end

subgraph group_external["External Services"]
  node_drive["Google Drive<br/>file storage integration"]
  node_messaging["LINE + SMTP Delivery<br/>communication adapters<br/>[line_client.py]"]
end

node_mobile_app -->|"renders"| node_navigation
node_navigation -->|"uses"| node_api_client
node_api_client -->|"caches offline state"| node_offline_cache
node_api_client -->|"HTTPS + JWT"| node_fastapi
node_contract -.->|"defines"| node_fastapi
node_fastapi -->|"applies"| node_auth_boundary
node_auth_boundary -->|"validates tokens"| node_auth_service
node_fastapi -->|"mounts"| node_domain_routers
node_fastapi -->|"mounts"| node_upload_evidence_api
node_domain_routers -->|"customer workflows"| node_customer_services
node_domain_routers -->|"tasks and touches"| node_automation
node_upload_evidence_api -->|"imports"| node_import_pipeline
node_upload_evidence_api -->|"manages evidence"| node_evidence_service
node_customer_services -->|"reads and writes"| node_repositories
node_automation -->|"manages task state"| node_repositories
node_import_pipeline -->|"persists imported data"| node_repositories
node_evidence_service -->|"records evidence"| node_repositories
node_reporting -->|"aggregates CRM data"| node_repositories
node_repositories -->|"uses sessions"| node_database
node_database -->|"connects"| node_mysql_schema
node_evidence_service -->|"stores files"| node_drive
node_automation -->|"delivers touchpoints"| node_messaging

click node_contract "https://github.com/piriyalapa/project-lumine/blob/main/openapi.yaml"
click node_mobile_app "https://github.com/piriyalapa/project-lumine/blob/main/mobile/App.tsx"
click node_navigation "https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/navigation/AppNavigator.tsx"
click node_api_client "https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/api/client.ts"
click node_offline_cache "https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/cache/offlineCache.ts"
click node_fastapi "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/main.py"
click node_auth_boundary "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/middleware/auth.py"
click node_auth_service "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/auth_service.py"
click node_domain_routers "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/routers/auto_touch.py"
click node_upload_evidence_api "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/routers/upload.py"
click node_customer_services "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/customer_register_service.py"
click node_automation "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/task_scheduler.py"
click node_import_pipeline "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/crm_import_service.py"
click node_evidence_service "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/evidence_service.py"
click node_reporting "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/dashboard_service.py"
click node_repositories "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/repositories/customer_repo.py"
click node_database "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/database.py"
click node_drive "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/google_drive_client.py"
click node_messaging "https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/line_client.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_app,node_navigation,node_api_client,node_offline_cache toneBlue
class node_contract,node_fastapi,node_auth_boundary,node_auth_service,node_domain_routers,node_upload_evidence_api toneAmber
class node_customer_services,node_automation,node_import_pipeline,node_evidence_service,node_reporting toneMint
class node_repositories,node_database,node_mysql_schema toneRose
class node_drive,node_messaging toneIndigo
```

## Components

### Mobile Client

- [Expo App](https://github.com/piriyalapa/project-lumine/blob/main/mobile/App.tsx): React Native entry · `mobile/App.tsx`
- [App Navigation](https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/navigation/AppNavigator.tsx): screen composition · `mobile/src/navigation/AppNavigator.tsx`
- [API + JWT Client](https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/api/client.ts): Axios client · `mobile/src/api/client.ts`
- [Offline UI Cache](https://github.com/piriyalapa/project-lumine/blob/main/mobile/src/cache/offlineCache.ts): cache boundary · `mobile/src/cache/offlineCache.ts`

### Backend API

- [OpenAPI Contract](https://github.com/piriyalapa/project-lumine/blob/main/openapi.yaml): API specification · Authoritative API contract. · `openapi.yaml`
- [FastAPI Application](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/main.py): backend entry · `backend/app/main.py`
- [JWT Auth Middleware](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/middleware/auth.py): authorization boundary · `backend/app/middleware/auth.py`
- [Auth Service](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/auth_service.py): credential service · `backend/app/services/auth_service.py`
- [Task + Auto-touch API](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/routers/auto_touch.py): domain routers · `backend/app/routers/auto_touch.py`
- [Upload + Evidence API](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/routers/upload.py): domain routers · `backend/app/routers/upload.py`

### CRM Automation

- [Customer Lifecycle](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/customer_register_service.py): profile services · Combines customer, transaction, and task state. · `backend/app/services/customer_register_service.py`
- [2-2-2 Automation](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/task_scheduler.py): scheduler services · Generates follow-up tasks and touchpoints. · `backend/app/services/task_scheduler.py`
- [CRM/SAP Import](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/crm_import_service.py): ingestion service · `backend/app/services/crm_import_service.py`
- [Evidence Service](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/evidence_service.py): evidence domain · `backend/app/services/evidence_service.py`
- [Dashboard + Reports](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/dashboard_service.py): aggregation service · `backend/app/services/dashboard_service.py`

### Persistence

- [Repositories](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/repositories/customer_repo.py): data access layer · Isolates CRM database queries. · `backend/app/repositories/customer_repo.py`
- [SQLAlchemy Session](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/database.py): database setup · `backend/app/database.py`
- **MySQL CRM Schema**: durable entities · Customers, staff, stores, transactions, tasks, messages, evidence, and uploads.

### External Services

- [Google Drive](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/google_drive_client.py): file storage integration · `backend/app/services/google_drive_client.py`
- [LINE + SMTP Delivery](https://github.com/piriyalapa/project-lumine/blob/main/backend/app/services/line_client.py): communication adapters · `backend/app/services/line_client.py`

## Connections

- Expo App → App Navigation: renders
- App Navigation → API + JWT Client: uses
- API + JWT Client → Offline UI Cache: caches offline state
- API + JWT Client → FastAPI Application: HTTPS + JWT
- OpenAPI Contract → FastAPI Application: defines
- FastAPI Application → JWT Auth Middleware: applies
- JWT Auth Middleware → Auth Service: validates tokens
- FastAPI Application → Task + Auto-touch API: mounts
- FastAPI Application → Upload + Evidence API: mounts
- Task + Auto-touch API → Customer Lifecycle: customer workflows
- Task + Auto-touch API → 2-2-2 Automation: tasks and touches
- Upload + Evidence API → CRM/SAP Import: imports
- Upload + Evidence API → Evidence Service: manages evidence
- Customer Lifecycle → Repositories: reads and writes
- 2-2-2 Automation → Repositories: manages task state
- CRM/SAP Import → Repositories: persists imported data
- Evidence Service → Repositories: records evidence
- Dashboard + Reports → Repositories: aggregates CRM data
- Repositories → SQLAlchemy Session: uses sessions
- SQLAlchemy Session → MySQL CRM Schema: connects
- Evidence Service → Google Drive: stores files
- 2-2-2 Automation → LINE + SMTP Delivery: delivers touchpoints