# pcharan30/cablesync architecture

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

- Interactive diagram: https://gitdiagram.com/pcharan30/cablesync
- Repository: https://github.com/pcharan30/cablesync

## Overview

CableSync supports operator-managed cable billing and a separate authenticated subscriber experience through one API backed by MongoDB. Operators manage customer records and collections, review reports and payment proofs, and handle support tickets; subscribers verify their phone and CAF identity, then view billing and payments, submit payment proofs, or raise support requests. The operator portal also queues selected work offline for later synchronization. Major capabilities are reflected from the README and tree; unsampled routes and controllers are represented at their existing directories, with only documented or evidenced connections shown.

Main entry points: [`backend/controllers/customerPortalController.js`](https://github.com/pcharan30/cablesync/blob/main/backend/controllers/customerPortalController.js) (Subscriber services), [`backend/server.js`](https://github.com/pcharan30/cablesync/blob/main/backend/server.js) (API server), [`backend/controllers`](https://github.com/pcharan30/cablesync/tree/main/backend/controllers) (Operator features), [`operator-portal/src/App.jsx`](https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/App.jsx) (Operator app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator portal"]
  node_operator_app["Operator app<br/>[App.jsx]"]
  node_operator_api["API client<br/>[api.js]"]
  node_offline_store[("Offline outbox<br/>[offlineStore.js]")]
  node_sync["Sync engine<br/>[syncEngine.js]"]
end

subgraph group_subscriber["Subscriber portal"]
  node_subscriber_app["Subscriber app<br/>[App.jsx]"]
  node_subscriber_api["API client<br/>[api.js]"]
end

subgraph group_backend["Backend API"]
  node_server["API server<br/>[server.js]"]
  node_customer_routes["Customer routes<br/>[customerRoutes.js]"]
  node_portal_routes["Subscriber routes"]
  node_payment_routes["Payment routes<br/>[paymentRoutes.js]"]
  node_business_controllers["Operator features"]
  node_portal_controller["Subscriber services"]
  node_proof_controller["Payment proofs"]
  node_identity["Customer identity"]
  node_billing["Billing logic<br/>[billingService.js]"]
  node_auth["Token signing<br/>[jwt.js]"]
end

subgraph group_data["Persistence"]
  node_db_config["Database connection<br/>[db.js]"]
  node_customer_model["Customer records<br/>[Customer.js]"]
  node_payment_model["Payment records<br/>[Payment.js]"]
  node_ticket_model["Support tickets<br/>[Ticket.js]"]
  node_proof_model["Proof records<br/>[PaymentProof.js]"]
end

node_operator(("Operator"))
node_subscriber(("Subscriber"))
node_mongo[("MongoDB Atlas")]

node_operator -->|"uses"| node_operator_app
node_operator_app -->|"requests"| node_operator_api
node_operator_app -->|"queues offline"| node_offline_store
node_operator_app -->|"starts sync"| node_sync
node_sync -->|"reads and updates"| node_offline_store
node_sync -->|"dispatches requests"| node_operator_api
node_subscriber -->|"uses"| node_subscriber_app
node_subscriber_app -->|"requests"| node_subscriber_api
node_operator_api -->|"calls API"| node_server
node_subscriber_api -->|"calls API"| node_server
node_server -->|"mounts"| node_customer_routes
node_server -->|"mounts"| node_portal_routes
node_server -->|"mounts"| node_payment_routes
node_server -->|"mounts feature routes"| node_business_controllers
node_customer_routes -->|"dispatches"| node_business_controllers
node_payment_routes -->|"dispatches"| node_business_controllers
node_portal_routes -->|"resolves subscriber"| node_identity
node_portal_routes -->|"dispatches"| node_portal_controller
node_portal_routes -->|"dispatches"| node_proof_controller
node_portal_controller -->|"issues token"| node_auth
node_portal_controller -->|"computes charges"| node_billing
node_business_controllers -->|"computes charges"| node_billing
node_business_controllers -->|"reads and writes"| node_customer_model
node_business_controllers -->|"reads and writes"| node_payment_model
node_portal_controller -->|"reads and writes"| node_customer_model
node_portal_controller -->|"reads and writes"| node_payment_model
node_portal_controller -->|"reads and writes"| node_ticket_model
node_proof_controller -->|"reads and writes"| node_proof_model
node_db_config -->|"connects"| node_mongo

click node_operator_app "https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/App.jsx"
click node_operator_api "https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/api.js"
click node_offline_store "https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/offlineStore.js"
click node_sync "https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/syncEngine.js"
click node_subscriber_app "https://github.com/pcharan30/cablesync/blob/main/subscriber-portal/src/App.jsx"
click node_subscriber_api "https://github.com/pcharan30/cablesync/blob/main/subscriber-portal/src/services/api.js"
click node_server "https://github.com/pcharan30/cablesync/blob/main/backend/server.js"
click node_customer_routes "https://github.com/pcharan30/cablesync/blob/main/backend/routes/customerRoutes.js"
click node_portal_routes "https://github.com/pcharan30/cablesync/blob/main/backend/routes/customerPortalRoutes.js"
click node_payment_routes "https://github.com/pcharan30/cablesync/blob/main/backend/routes/paymentRoutes.js"
click node_business_controllers "https://github.com/pcharan30/cablesync/tree/main/backend/controllers"
click node_portal_controller "https://github.com/pcharan30/cablesync/blob/main/backend/controllers/customerPortalController.js"
click node_proof_controller "https://github.com/pcharan30/cablesync/blob/main/backend/controllers/paymentProofController.js"
click node_identity "https://github.com/pcharan30/cablesync/blob/main/backend/middleware/resolvePublicCustomer.js"
click node_billing "https://github.com/pcharan30/cablesync/blob/main/backend/services/billingService.js"
click node_auth "https://github.com/pcharan30/cablesync/blob/main/backend/utils/jwt.js"
click node_db_config "https://github.com/pcharan30/cablesync/blob/main/backend/config/db.js"
click node_customer_model "https://github.com/pcharan30/cablesync/blob/main/backend/models/Customer.js"
click node_payment_model "https://github.com/pcharan30/cablesync/blob/main/backend/models/Payment.js"
click node_ticket_model "https://github.com/pcharan30/cablesync/blob/main/backend/models/Ticket.js"
click node_proof_model "https://github.com/pcharan30/cablesync/blob/main/backend/models/PaymentProof.js"

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_operator_app,node_operator_api,node_offline_store,node_sync toneBlue
class node_subscriber_app,node_subscriber_api,node_mongo toneAmber
class node_server,node_customer_routes,node_portal_routes,node_payment_routes,node_business_controllers,node_portal_controller,node_proof_controller,node_identity,node_billing,node_auth toneMint
class node_db_config,node_customer_model,node_payment_model,node_ticket_model,node_proof_model toneRose
class node_operator,node_subscriber toneIndigo
```

## Components

### Operator portal

- [Operator app](https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/App.jsx): `operator-portal/src/App.jsx`
- [API client](https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/api.js): `operator-portal/src/services/api.js`
- [Offline outbox](https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/offlineStore.js): `operator-portal/src/services/offlineStore.js`
- [Sync engine](https://github.com/pcharan30/cablesync/blob/main/operator-portal/src/services/syncEngine.js): `operator-portal/src/services/syncEngine.js`

### Subscriber portal

- [Subscriber app](https://github.com/pcharan30/cablesync/blob/main/subscriber-portal/src/App.jsx): `subscriber-portal/src/App.jsx`
- [API client](https://github.com/pcharan30/cablesync/blob/main/subscriber-portal/src/services/api.js): `subscriber-portal/src/services/api.js`

### Backend API

- [API server](https://github.com/pcharan30/cablesync/blob/main/backend/server.js): `backend/server.js`
- [Customer routes](https://github.com/pcharan30/cablesync/blob/main/backend/routes/customerRoutes.js): `backend/routes/customerRoutes.js`
- [Subscriber routes](https://github.com/pcharan30/cablesync/blob/main/backend/routes/customerPortalRoutes.js): `backend/routes/customerPortalRoutes.js`
- [Payment routes](https://github.com/pcharan30/cablesync/blob/main/backend/routes/paymentRoutes.js): `backend/routes/paymentRoutes.js`
- [Operator features](https://github.com/pcharan30/cablesync/tree/main/backend/controllers): `backend/controllers`
- [Subscriber services](https://github.com/pcharan30/cablesync/blob/main/backend/controllers/customerPortalController.js): `backend/controllers/customerPortalController.js`
- [Payment proofs](https://github.com/pcharan30/cablesync/blob/main/backend/controllers/paymentProofController.js): `backend/controllers/paymentProofController.js`
- [Customer identity](https://github.com/pcharan30/cablesync/blob/main/backend/middleware/resolvePublicCustomer.js): `backend/middleware/resolvePublicCustomer.js`
- [Billing logic](https://github.com/pcharan30/cablesync/blob/main/backend/services/billingService.js): `backend/services/billingService.js`
- [Token signing](https://github.com/pcharan30/cablesync/blob/main/backend/utils/jwt.js): `backend/utils/jwt.js`

### Persistence

- [Database connection](https://github.com/pcharan30/cablesync/blob/main/backend/config/db.js): `backend/config/db.js`
- [Customer records](https://github.com/pcharan30/cablesync/blob/main/backend/models/Customer.js): `backend/models/Customer.js`
- [Payment records](https://github.com/pcharan30/cablesync/blob/main/backend/models/Payment.js): `backend/models/Payment.js`
- [Support tickets](https://github.com/pcharan30/cablesync/blob/main/backend/models/Ticket.js): `backend/models/Ticket.js`
- [Proof records](https://github.com/pcharan30/cablesync/blob/main/backend/models/PaymentProof.js): `backend/models/PaymentProof.js`

### Other components

- **Operator**
- **Subscriber**
- **MongoDB Atlas**

## Connections

- Operator → Operator app: uses
- Operator app → API client: requests
- Operator app → Offline outbox: queues offline
- Operator app → Sync engine: starts sync
- Sync engine → Offline outbox: reads and updates
- Sync engine → API client: dispatches requests
- Subscriber → Subscriber app: uses
- Subscriber app → API client: requests
- API client → API server: calls API
- API client → API server: calls API
- API server → Customer routes: mounts
- API server → Subscriber routes: mounts
- API server → Payment routes: mounts
- API server → Operator features: mounts feature routes
- Customer routes → Operator features: dispatches
- Payment routes → Operator features: dispatches
- Subscriber routes → Customer identity: resolves subscriber
- Subscriber routes → Subscriber services: dispatches
- Subscriber routes → Payment proofs: dispatches
- Subscriber services → Token signing: issues token
- Subscriber services → Billing logic: computes charges
- Operator features → Billing logic: computes charges
- Operator features → Customer records: reads and writes
- Operator features → Payment records: reads and writes
- Subscriber services → Customer records: reads and writes
- Subscriber services → Payment records: reads and writes
- Subscriber services → Support tickets: reads and writes
- Payment proofs → Proof records: reads and writes
- Database connection → MongoDB Atlas: connects