piriyalapa/project-lumine

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.