# karimmalidev/qisto architecture

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

- Interactive diagram: https://gitdiagram.com/karimmalidev/qisto
- Repository: https://github.com/karimmalidev/qisto

## Overview

Qisto is an installment-sales management app with a React client and Express API. Users sign in, manage customers and products, and create installment contracts; the API also accepts and returns synchronized operations for customers, products, contracts, schedules, payments, and allocations. The client initializes a local database and exposes customer/product screens and contract creation. Source evidence is strongest for API composition, authentication, and sync dispatch; the README is empty, and several client feature files were not excerpted, so uncertain UI-to-service links are omitted.

Main entry points: [`apps/client/src/main.tsx`](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/main.tsx) (Client routing), [`apps/api/src/app-container.ts`](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app-container.ts) (Service composition), [`apps/client/src/db/index.ts`](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/db/index.ts) (Local database), [`apps/client/src/api-client.ts`](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client application"]
  node_client_app["Client routing<br/>[main.tsx]"]
  node_auth_ui["Sign-in UI<br/>[login-page.tsx]"]
  node_auth_state["Client auth state<br/>[auth-provider.tsx]"]
  node_customer_ui["Customer management<br/>[customers-page.tsx]"]
  node_product_ui["Product management<br/>[products-page.tsx]"]
  node_contract_ui["Contract creation"]
  node_client_db[("Local database<br/>[index.ts]")]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_api["API and authentication"]
  node_api_app["HTTP application<br/>[app.ts]"]
  node_router["API router<br/>[app-router.ts]"]
  node_container["Service composition<br/>[app-container.ts]"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
end

subgraph group_sync["Synchronization"]
  node_sync_controller["Sync controller<br/>[sync.controller.ts]"]
  node_sync_service["Sync service<br/>[sync.service.ts]"]
  node_operation_service["Operation dispatch"]
end

subgraph group_domain["Sales domain and persistence"]
  node_resource_services["Resource upserts"]
  node_api_db[("Server database<br/>[schema.ts]")]
end

subgraph group_contracts["Shared contracts"]
  node_shared_schemas["Shared schemas"]
end

node_user(("User"))

node_user -->|"uses"| node_client_app
node_client_app -->|"routes to"| node_auth_ui
node_client_app -->|"routes to"| node_customer_ui
node_client_app -->|"routes to"| node_product_ui
node_client_app -->|"routes to"| node_contract_ui
node_client_app -->|"initializes"| node_client_db
node_api_app -->|"mounts"| node_router
node_router -->|"uses"| node_container
node_container -->|"constructs"| node_auth_controller
node_container -->|"constructs"| node_auth_service
node_container -->|"constructs"| node_sync_controller
node_container -->|"constructs"| node_sync_service
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"reads and writes"| node_api_db
node_sync_controller -->|"calls"| node_sync_service
node_sync_service -->|"dispatches"| node_operation_service
node_operation_service -->|"dispatches upserts"| node_resource_services
node_operation_service -->|"stores and queries"| node_api_db
node_resource_services -->|"reads and writes"| node_api_db
node_api_client -.->|"sends requests"| node_api_app
node_api_client -->|"shares token store"| node_auth_state
node_customer_ui -.->|"uses local data"| node_client_db
node_product_ui -.->|"uses local data"| node_client_db
node_contract_ui -.->|"uses local data"| node_client_db
node_api_client -->|"validates contracts"| node_shared_schemas
node_auth_controller -->|"parses login"| node_shared_schemas
node_sync_controller -->|"parses sync"| node_shared_schemas

click node_client_app "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/main.tsx"
click node_auth_ui "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/login/login-page.tsx"
click node_auth_state "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/features/auth/auth-provider.tsx"
click node_customer_ui "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/customers/customers-page.tsx"
click node_product_ui "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/products/products-page.tsx"
click node_contract_ui "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/installment-contracts/create/create-installment-contract-page.tsx"
click node_client_db "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/db/index.ts"
click node_api_client "https://github.com/karimmalidev/qisto/blob/main/apps/client/src/api-client.ts"
click node_api_app "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app.ts"
click node_router "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app-router.ts"
click node_container "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app-container.ts"
click node_auth_controller "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_sync_controller "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/sync/sync.controller.ts"
click node_sync_service "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/sync/sync.service.ts"
click node_operation_service "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/resources/operation.service.ts"
click node_resource_services "https://github.com/karimmalidev/qisto/tree/main/apps/api/src/modules/resources"
click node_api_db "https://github.com/karimmalidev/qisto/blob/main/apps/api/src/db/schema.ts"
click node_shared_schemas "https://github.com/karimmalidev/qisto/tree/main/packages/schemas/src/schemas"

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_client_app,node_auth_ui,node_auth_state,node_customer_ui,node_product_ui,node_contract_ui,node_client_db,node_api_client,node_user toneBlue
class node_api_app,node_router,node_container,node_auth_controller,node_auth_service toneAmber
class node_sync_controller,node_sync_service,node_operation_service toneMint
class node_resource_services,node_api_db toneRose
class node_shared_schemas toneIndigo
```

## Components

### Client application

- [Client routing](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/main.tsx): `apps/client/src/main.tsx`
- [Sign-in UI](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/login/login-page.tsx): `apps/client/src/pages/login/login-page.tsx`
- [Client auth state](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/features/auth/auth-provider.tsx): `apps/client/src/features/auth/auth-provider.tsx`
- [Customer management](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/customers/customers-page.tsx): `apps/client/src/pages/customers/customers-page.tsx`
- [Product management](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/products/products-page.tsx): `apps/client/src/pages/products/products-page.tsx`
- [Contract creation](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/pages/installment-contracts/create/create-installment-contract-page.tsx): `apps/client/src/pages/installment-contracts/create/create-installment-contract-page.tsx`
- [Local database](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/db/index.ts): `apps/client/src/db/index.ts`
- [API client](https://github.com/karimmalidev/qisto/blob/main/apps/client/src/api-client.ts): `apps/client/src/api-client.ts`

### API and authentication

- [HTTP application](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [API router](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app-router.ts): `apps/api/src/app-router.ts`
- [Service composition](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/app-container.ts): `apps/api/src/app-container.ts`
- [Auth controller](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`

### Synchronization

- [Sync controller](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/sync/sync.controller.ts): `apps/api/src/modules/sync/sync.controller.ts`
- [Sync service](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/sync/sync.service.ts): `apps/api/src/modules/sync/sync.service.ts`
- [Operation dispatch](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/modules/resources/operation.service.ts): `apps/api/src/modules/resources/operation.service.ts`

### Sales domain and persistence

- [Resource upserts](https://github.com/karimmalidev/qisto/tree/main/apps/api/src/modules/resources): `apps/api/src/modules/resources`
- [Server database](https://github.com/karimmalidev/qisto/blob/main/apps/api/src/db/schema.ts): `apps/api/src/db/schema.ts`

### Shared contracts

- [Shared schemas](https://github.com/karimmalidev/qisto/tree/main/packages/schemas/src/schemas): `packages/schemas/src/schemas`

### Other components

- **User**

## Connections

- User → Client routing: uses
- Client routing → Sign-in UI: routes to (evidence: `apps/client/src/main.tsx`)
- Client routing → Customer management: routes to (evidence: `apps/client/src/main.tsx`)
- Client routing → Product management: routes to (evidence: `apps/client/src/main.tsx`)
- Client routing → Contract creation: routes to (evidence: `apps/client/src/main.tsx`)
- Client routing → Local database: initializes (evidence: `apps/client/src/main.tsx`)
- HTTP application → API router: mounts (evidence: `apps/api/src/app.ts`)
- API router → Service composition: uses (evidence: `apps/api/src/app-router.ts`)
- Service composition → Auth controller: constructs (evidence: `apps/api/src/app-container.ts`)
- Service composition → Auth service: constructs (evidence: `apps/api/src/app-container.ts`)
- Service composition → Sync controller: constructs (evidence: `apps/api/src/app-container.ts`)
- Service composition → Sync service: constructs (evidence: `apps/api/src/app-container.ts`)
- Auth controller → Auth service: calls (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Auth service → Server database: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Sync controller → Sync service: calls (evidence: `apps/api/src/modules/sync/sync.controller.ts`)
- Sync service → Operation dispatch: dispatches (evidence: `apps/api/src/modules/sync/sync.service.ts`)
- Operation dispatch → Resource upserts: dispatches upserts (evidence: `apps/api/src/modules/resources/operation.service.ts`)
- Operation dispatch → Server database: stores and queries (evidence: `apps/api/src/modules/resources/operation.service.ts`)
- Resource upserts → Server database: reads and writes (evidence: `apps/api/src/modules/resources/installment-contract.service.ts`)
- API client → HTTP application: sends requests
- API client → Client auth state: shares token store (evidence: `apps/client/src/api-client.ts`)
- Customer management → Local database: uses local data
- Product management → Local database: uses local data
- Contract creation → Local database: uses local data
- API client → Shared schemas: validates contracts (evidence: `apps/client/src/api-client.ts`)
- Auth controller → Shared schemas: parses login (evidence: `apps/api/src/modules/auth/auth.controller.ts`)
- Sync controller → Shared schemas: parses sync (evidence: `apps/api/src/modules/sync/sync.controller.ts`)
