# tara1903/starx-flow architecture

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

- Interactive diagram: https://gitdiagram.com/tara1903/starx-flow
- Repository: https://github.com/tara1903/starx-flow

## Overview

StarXFlow is a multi-tenant AI customer-engagement and business-operations platform, with a web dashboard and a Kotlin Multiplatform mobile client. Users configure channels and business knowledge, receive customer conversations, use AI-assisted responses and workflows, and manage customers, appointments, orders, and analytics. The graph shows documented web API orchestration and mobile app composition; several major capabilities are present in the tree but their runtime wiring was not sampled, so those links are left unverified rather than asserted.

Main entry points: [`src/components/ClientShell.tsx`](https://github.com/tara1903/starx-flow/blob/main/src/components/ClientShell.tsx) (Web application shell), [`mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt`](https://github.com/tara1903/starx-flow/blob/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt) (Mobile app navigation), [`src/app/api/chat/route.ts`](https://github.com/tara1903/starx-flow/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/app/api/orders/route.ts`](https://github.com/tara1903/starx-flow/blob/main/src/app/api/orders/route.ts) (Order management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Web and Mobile Clients"]
  node_webshell["Web application shell<br/>[ClientShell.tsx]"]
  node_signup["Signup flow<br/>[SignupModal.tsx]"]
  node_auth["Web authentication state<br/>[authStore.ts]"]
  node_mobileapp["Mobile app navigation<br/>[App.kt]"]
  node_mobileviews["Mobile feature screens"]
  node_mobilevm["Mobile view models"]
  node_mobiledata["Mobile data repositories"]
  node_mobileapi["Mobile API client<br/>[StarXApiClient.kt]"]
end

subgraph group_engagement["Customer Engagement"]
  node_inbox["Conversation inbox<br/>[inboxService.ts]"]
  node_ingestion["Channel ingestion<br/>[gateway.ts]"]
  node_chatapi["Chat API<br/>[route.ts]"]
  node_ai["AI response orchestration<br/>[orchestrator.ts]"]
  node_knowledge["Knowledge retrieval<br/>[knowledgeEngine.ts]"]
  node_rag[("Tenant-isolated RAG<br/>[multiTenantRAG.ts]")]
  node_dispatcher["Outbound dispatcher"]
  node_integrations["Messaging integrations"]
end

subgraph group_operations["Business Operations"]
  node_dashboard["Operations dashboard"]
  node_workflows["Workflow automation"]
  node_calendar["Calendar integrations"]
  node_crm["Customer identity and CRM"]
  node_orders["Order management API<br/>[route.ts]"]
end

subgraph group_platform["Platform Services"]
  node_securestorage["Secure credential storage<br/>[SecureStorage.kt]"]
  node_scheduler["Scheduled jobs"]
  node_usage["Usage metering<br/>[usageService.ts]"]
  node_adminstore[("Admin data access<br/>[supabaseAdmin.ts]")]
  node_datamodel["Business data types<br/>[database.ts]"]
  node_billing["Billing checkout<br/>[polar.ts]"]
end

node_customer(("Business user"))

node_customer -->|"uses"| node_webshell
node_webshell -->|"opens"| node_signup
node_webshell -->|"initializes session"| node_auth
node_customer -->|"uses"| node_mobileapp
node_mobileapp -->|"routes to"| node_mobileviews
node_mobileapp -->|"provides"| node_mobilevm
node_mobilevm -.->|"uses"| node_mobiledata
node_mobiledata -.->|"calls"| node_mobileapi
node_mobileapi -->|"uses credentials"| node_securestorage
node_customer -.->|"manages operations"| node_dashboard
node_customer -.->|"sends chat"| node_chatapi
node_chatapi -->|"ingests message"| node_ingestion
node_chatapi -->|"records usage"| node_usage
node_ingestion -.->|"routes messages"| node_inbox
node_inbox -.->|"requests responses"| node_ai
node_ai -.->|"retrieves context"| node_knowledge
node_knowledge -->|"ingests and retrieves"| node_rag
node_customer -.->|"configures"| node_workflows
node_customer -.->|"connects calendar"| node_calendar
node_customer -.->|"manages customers"| node_crm
node_customer -.->|"manages orders"| node_orders
node_orders -->|"reads and writes"| node_adminstore
node_orders -.->|"uses types"| node_datamodel
node_scheduler -->|"dispatches jobs"| node_dispatcher
node_customer -.->|"connects channels"| node_integrations
node_customer -.->|"checks out"| node_billing

click node_webshell "https://github.com/tara1903/starx-flow/blob/main/src/components/ClientShell.tsx"
click node_signup "https://github.com/tara1903/starx-flow/blob/main/src/components/SignupModal.tsx"
click node_auth "https://github.com/tara1903/starx-flow/blob/main/src/store/authStore.ts"
click node_mobileapp "https://github.com/tara1903/starx-flow/blob/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt"
click node_mobileviews "https://github.com/tara1903/starx-flow/tree/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/screens"
click node_mobilevm "https://github.com/tara1903/starx-flow/tree/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/viewmodel"
click node_mobiledata "https://github.com/tara1903/starx-flow/tree/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/repository"
click node_mobileapi "https://github.com/tara1903/starx-flow/blob/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/network/StarXApiClient.kt"
click node_securestorage "https://github.com/tara1903/starx-flow/blob/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/auth/SecureStorage.kt"
click node_dashboard "https://github.com/tara1903/starx-flow/tree/main/src/screens/dashboard"
click node_inbox "https://github.com/tara1903/starx-flow/blob/main/src/lib/inbox/inboxService.ts"
click node_ingestion "https://github.com/tara1903/starx-flow/blob/main/src/lib/ingestion/gateway.ts"
click node_chatapi "https://github.com/tara1903/starx-flow/blob/main/src/app/api/chat/route.ts"
click node_ai "https://github.com/tara1903/starx-flow/blob/main/src/lib/ai/orchestrator.ts"
click node_knowledge "https://github.com/tara1903/starx-flow/blob/main/src/lib/ai/knowledgeEngine.ts"
click node_rag "https://github.com/tara1903/starx-flow/blob/main/src/lib/rag/multiTenantRAG.ts"
click node_workflows "https://github.com/tara1903/starx-flow/blob/main/src/screens/dashboard/WorkflowsSection.tsx"
click node_calendar "https://github.com/tara1903/starx-flow/blob/main/src/lib/integrations/calendar/calendarSyncService.ts"
click node_crm "https://github.com/tara1903/starx-flow/blob/main/src/lib/crm/identityResolver.ts"
click node_orders "https://github.com/tara1903/starx-flow/blob/main/src/app/api/orders/route.ts"
click node_scheduler "https://github.com/tara1903/starx-flow/blob/main/src/lib/jobs/receptionistJobScheduler.ts"
click node_dispatcher "https://github.com/tara1903/starx-flow/blob/main/src/lib/inbox/outboundDispatcher.ts"
click node_usage "https://github.com/tara1903/starx-flow/blob/main/src/lib/usage/usageService.ts"
click node_adminstore "https://github.com/tara1903/starx-flow/blob/main/src/lib/supabaseAdmin.ts"
click node_datamodel "https://github.com/tara1903/starx-flow/blob/main/src/types/database.ts"
click node_integrations "https://github.com/tara1903/starx-flow/tree/main/src/app/api/integrations"
click node_billing "https://github.com/tara1903/starx-flow/blob/main/src/lib/polar.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_webshell,node_signup,node_auth,node_mobileapp,node_mobileviews,node_mobilevm,node_mobiledata,node_mobileapi,node_customer toneBlue
class node_inbox,node_ingestion,node_chatapi,node_ai,node_knowledge,node_rag,node_dispatcher,node_integrations toneAmber
class node_dashboard,node_workflows,node_calendar,node_crm,node_orders toneMint
class node_securestorage,node_scheduler,node_usage,node_adminstore,node_datamodel,node_billing toneRose
```

## Components

### Web and Mobile Clients

- [Web application shell](https://github.com/tara1903/starx-flow/blob/main/src/components/ClientShell.tsx): `src/components/ClientShell.tsx`
- [Signup flow](https://github.com/tara1903/starx-flow/blob/main/src/components/SignupModal.tsx): `src/components/SignupModal.tsx`
- [Web authentication state](https://github.com/tara1903/starx-flow/blob/main/src/store/authStore.ts): `src/store/authStore.ts`
- [Mobile app navigation](https://github.com/tara1903/starx-flow/blob/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt): `mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt`
- [Mobile feature screens](https://github.com/tara1903/starx-flow/tree/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/screens): `mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/screens`
- [Mobile view models](https://github.com/tara1903/starx-flow/tree/main/mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/viewmodel): `mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/ui/viewmodel`
- [Mobile data repositories](https://github.com/tara1903/starx-flow/tree/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/repository): `mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/repository`
- [Mobile API client](https://github.com/tara1903/starx-flow/blob/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/network/StarXApiClient.kt): `mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/network/StarXApiClient.kt`

### Customer Engagement

- [Conversation inbox](https://github.com/tara1903/starx-flow/blob/main/src/lib/inbox/inboxService.ts): `src/lib/inbox/inboxService.ts`
- [Channel ingestion](https://github.com/tara1903/starx-flow/blob/main/src/lib/ingestion/gateway.ts): `src/lib/ingestion/gateway.ts`
- [Chat API](https://github.com/tara1903/starx-flow/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [AI response orchestration](https://github.com/tara1903/starx-flow/blob/main/src/lib/ai/orchestrator.ts): `src/lib/ai/orchestrator.ts`
- [Knowledge retrieval](https://github.com/tara1903/starx-flow/blob/main/src/lib/ai/knowledgeEngine.ts): `src/lib/ai/knowledgeEngine.ts`
- [Tenant-isolated RAG](https://github.com/tara1903/starx-flow/blob/main/src/lib/rag/multiTenantRAG.ts): `src/lib/rag/multiTenantRAG.ts`
- [Outbound dispatcher](https://github.com/tara1903/starx-flow/blob/main/src/lib/inbox/outboundDispatcher.ts): `src/lib/inbox/outboundDispatcher.ts`
- [Messaging integrations](https://github.com/tara1903/starx-flow/tree/main/src/app/api/integrations): `src/app/api/integrations`

### Business Operations

- [Operations dashboard](https://github.com/tara1903/starx-flow/tree/main/src/screens/dashboard): `src/screens/dashboard`
- [Workflow automation](https://github.com/tara1903/starx-flow/blob/main/src/screens/dashboard/WorkflowsSection.tsx): `src/screens/dashboard/WorkflowsSection.tsx`
- [Calendar integrations](https://github.com/tara1903/starx-flow/blob/main/src/lib/integrations/calendar/calendarSyncService.ts): `src/lib/integrations/calendar/calendarSyncService.ts`
- [Customer identity and CRM](https://github.com/tara1903/starx-flow/blob/main/src/lib/crm/identityResolver.ts): `src/lib/crm/identityResolver.ts`
- [Order management API](https://github.com/tara1903/starx-flow/blob/main/src/app/api/orders/route.ts): `src/app/api/orders/route.ts`

### Platform Services

- [Secure credential storage](https://github.com/tara1903/starx-flow/blob/main/mobile/shared/src/commonMain/kotlin/com/starxflow/shared/auth/SecureStorage.kt): `mobile/shared/src/commonMain/kotlin/com/starxflow/shared/auth/SecureStorage.kt`
- [Scheduled jobs](https://github.com/tara1903/starx-flow/blob/main/src/lib/jobs/receptionistJobScheduler.ts): `src/lib/jobs/receptionistJobScheduler.ts`
- [Usage metering](https://github.com/tara1903/starx-flow/blob/main/src/lib/usage/usageService.ts): `src/lib/usage/usageService.ts`
- [Admin data access](https://github.com/tara1903/starx-flow/blob/main/src/lib/supabaseAdmin.ts): `src/lib/supabaseAdmin.ts`
- [Business data types](https://github.com/tara1903/starx-flow/blob/main/src/types/database.ts): `src/types/database.ts`
- [Billing checkout](https://github.com/tara1903/starx-flow/blob/main/src/lib/polar.ts): `src/lib/polar.ts`

### Other components

- **Business user**

## Connections

- Business user → Web application shell: uses
- Web application shell → Signup flow: opens (evidence: `src/components/ClientShell.tsx`)
- Web application shell → Web authentication state: initializes session (evidence: `src/components/ClientShell.tsx`)
- Business user → Mobile app navigation: uses
- Mobile app navigation → Mobile feature screens: routes to (evidence: `mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt`)
- Mobile app navigation → Mobile view models: provides (evidence: `mobile/composeApp/src/commonMain/kotlin/com/starxflow/mobile/App.kt`)
- Mobile view models → Mobile data repositories: uses
- Mobile data repositories → Mobile API client: calls (evidence: `mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/repository/AuthRepositoryImpl.kt`)
- Mobile API client → Secure credential storage: uses credentials (evidence: `mobile/shared/src/commonMain/kotlin/com/starxflow/shared/data/network/StarXApiClient.kt`)
- Business user → Operations dashboard: manages operations
- Business user → Chat API: sends chat
- Chat API → Channel ingestion: ingests message (evidence: `src/app/api/chat/route.ts`)
- Chat API → Usage metering: records usage (evidence: `src/app/api/chat/route.ts`)
- Channel ingestion → Conversation inbox: routes messages
- Conversation inbox → AI response orchestration: requests responses
- AI response orchestration → Knowledge retrieval: retrieves context
- Knowledge retrieval → Tenant-isolated RAG: ingests and retrieves (evidence: `src/lib/ai/knowledgeEngine.ts`)
- Business user → Workflow automation: configures
- Business user → Calendar integrations: connects calendar
- Business user → Customer identity and CRM: manages customers
- Business user → Order management API: manages orders
- Order management API → Admin data access: reads and writes (evidence: `src/app/api/orders/route.ts`)
- Order management API → Business data types: uses types
- Scheduled jobs → Outbound dispatcher: dispatches jobs (evidence: `src/app/api/cron/process-jobs/route.ts`)
- Business user → Messaging integrations: connects channels
- Business user → Billing checkout: checks out
