# diwascha/starweb architecture

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

- Interactive diagram: https://gitdiagram.com/diwascha/starweb
- Repository: https://github.com/diwascha/starweb

## Overview

1. **Overall shape**
   - STARWEB is an internal operations suite built on **Next.js App Router** with modules for **HR, payroll, fleet, CRM, finance, procurement, reporting, products, and notes**.
   - The codebase is organized around domain areas rather than a single generic CRUD app.

2. **Primary runtime boundary**
   - The main application lives under `src/app`, where each folder is a route or route group.
   - Most pages are thin route shells that compose feature-specific client components from colocated `_components` folders.

3. **Presentation layer**
   - UI is built with **ShadCN UI**, **Tailwind CSS**, and **Lucide React** icons.
   - Shared primitives live in `src/components/ui`, while higher-level shells like the sidebar and auth-aware layout live in `src/components`.

4. **Navigation and app shell**
   - `src/components/app-sidebar.tsx` and `src/components/auth-aware-layout.tsx` define the main navigation and authenticated layout behavior.
   - This suggests a single authenticated workspace with module navigation, not a set of independent standalone apps.

5. **Backend and data boundary**
   - The app uses **Firebase** as its main backend, specifically **Firestore** and **Realtime Database**.
   - Firebase initialization and providers are centralized in `src/firebase` and mirrored under `src/lib/firebase`, indicating shared client-side access patterns.
   - `firestore.rules` is part of the repo, so security rules are treated as a first-class boundary.

6. **Service layer**
   - Business logic is concentrated in `src/services`, with per-domain services such as:
     - `employee-service`, `payroll-service`, `attendance-service`
     - `purchase-order-service`, `transaction-service`, `vehicle-service`, `driver-service`
     - `report-service`, `cost-report-service`, `cheque-service`, `estimate-invoice-service`
     - `storage-service`, `backup-service`, `google-sheets-service`
   - These services form the main abstraction between UI components and Firebase/external integrations.

7. **Feature workflows**
   - Many domains have both list/dashboard screens and form/detail screens, for example:
     - purchase orders: new, edit, list, view
     - fleet transactions: purchase and payment receipt flows
     - HR: employees, attendance, payroll import, payslip views
     - finance: cheque generator, estimate invoice, TDS calculator
   - The app is built around operational workflows that create, edit, preview, and print business documents.

8. **Document and report generation**
   - Several modules focus on document output rather than only data entry: purchase order views, payslips, quotations, invoices, cheques, trip sheets, and cost reports.
   - These are rendered as dedicated view components, implying the UI is also used for printable/exportable artifacts.

9. **AI subsystem**
   - `src/ai` contains **Genkit** flows, including:
     - `translate-to-nepali-flow`
     - `summarize-po-changes-flow`
   - AI is therefore a separate service-style capability, not embedded everywhere in the UI.

10. **External integrations**
   - Besides Firebase, the repo includes a **Google Sheets** integration and storage/backup services.
   - This points to hybrid data movement: operational data stays in Firebase, while certain workflows likely export, sync, or archive to external systems.

11. **Desktop packaging**
   - The presence of `src-tauri` indicates the app is also packaged as a **Tauri desktop application**.
   - That makes the frontend code serve both browser and desktop delivery, with Tauri handling the native shell layer.

12. **Cross-cutting concerns**
   - Shared hooks like `use-auth`, `use-connection-status`, `use-mobile`, and `use-toast` handle application-wide concerns.
   - `usage-tracker` suggests instrumentation/telemetry is part of the UI layer.
   - Fonts, constants, utilities, and type definitions in `src/lib` support reuse across modules.

Main entry points: [`src/services`](https://github.com/diwascha/starweb/tree/main/src/services) (Document Services), [`src/firebase`](https://github.com/diwascha/starweb/tree/main/src/firebase) (Firebase), [`src/components/auth-aware-layout.tsx`](https://github.com/diwascha/starweb/blob/main/src/components/auth-aware-layout.tsx) (App Shell), [`src/ai/flows`](https://github.com/diwascha/starweb/tree/main/src/ai/flows) (AI Flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_app_router["App Router<br/>nextjs routes"]
  node_app_shell["App Shell<br/>layout/nav"]
  node_sidebar["Sidebar<br/>navigation<br/>[app-sidebar.tsx]"]
  node_ui_primitives["UI Primitives<br/>shadcn ui"]
  node_shared_hooks["Shared Hooks<br/>client hooks"]
end

subgraph group_domains["Domain Workflows"]
  node_hr_module["HR<br/>domain module"]
  node_fleet_module["Fleet<br/>domain module"]
  node_finance_module["Finance<br/>domain module"]
  node_po_module["Purchase Orders<br/>workflow module"]
  node_crm_module["CRM / Cost Reports<br/>workflow module"]
  node_reporting_module["Reporting<br/>domain module"]
  node_notes_module["Notes<br/>workspace module"]
end

subgraph group_services["Services"]
  node_core_services["Core Services<br/>service layer"]
  node_document_services["Document Services<br/>service layer"]
  node_ops_services["Ops Services<br/>service layer"]
end

subgraph group_platform["Platform"]
  node_firebase_layer[("Firebase<br/>backend platform")]
  node_firestore_rules["Rules<br/>[firestore.rules]"]
  node_ai_flows{{"AI Flows<br/>genkit flows"}}
  node_google_sheets["Sheets Sync<br/>integration"]
end

subgraph group_desktop["Desktop"]
  node_tauri_shell["Tauri Shell<br/>desktop runtime"]
end

node_app_router -->|"renders"| node_app_shell
node_app_shell -->|"includes"| node_sidebar
node_app_shell -->|"builds with"| node_ui_primitives
node_app_shell -->|"uses"| node_shared_hooks
node_hr_module -->|"reads/writes"| node_core_services
node_fleet_module -->|"reads/writes"| node_ops_services
node_finance_module -->|"renders via"| node_document_services
node_po_module -->|"reads/writes"| node_document_services
node_crm_module -->|"reads/writes"| node_document_services
node_reporting_module -->|"reads/writes"| node_document_services
node_notes_module -->|"reads/writes"| node_core_services
node_core_services -->|"persists to"| node_firebase_layer
node_document_services -->|"persists to"| node_firebase_layer
node_ops_services -->|"persists to"| node_firebase_layer
node_firebase_layer -->|"governed by"| node_firestore_rules
node_ai_flows -.->|"augments"| node_core_services
node_ai_flows -.->|"consumes data"| node_firebase_layer
node_google_sheets -.->|"integrates with"| node_ops_services
node_tauri_shell -->|"packages"| node_app_router

click node_app_router "https://github.com/diwascha/starweb/tree/main/src/app"
click node_app_shell "https://github.com/diwascha/starweb/blob/main/src/components/auth-aware-layout.tsx"
click node_sidebar "https://github.com/diwascha/starweb/blob/main/src/components/app-sidebar.tsx"
click node_ui_primitives "https://github.com/diwascha/starweb/tree/main/src/components/ui"
click node_shared_hooks "https://github.com/diwascha/starweb/tree/main/src/hooks"
click node_hr_module "https://github.com/diwascha/starweb/tree/main/src/app/hr"
click node_fleet_module "https://github.com/diwascha/starweb/tree/main/src/app/fleet"
click node_finance_module "https://github.com/diwascha/starweb/tree/main/src/app/finance"
click node_po_module "https://github.com/diwascha/starweb/tree/main/src/app/purchase-orders"
click node_crm_module "https://github.com/diwascha/starweb/tree/main/src/app/crm"
click node_reporting_module "https://github.com/diwascha/starweb/tree/main/src/app/reports"
click node_notes_module "https://github.com/diwascha/starweb/tree/main/src/app/notes"
click node_core_services "https://github.com/diwascha/starweb/tree/main/src/services"
click node_document_services "https://github.com/diwascha/starweb/tree/main/src/services"
click node_ops_services "https://github.com/diwascha/starweb/tree/main/src/services"
click node_firebase_layer "https://github.com/diwascha/starweb/tree/main/src/firebase"
click node_firestore_rules "https://github.com/diwascha/starweb/blob/main/firestore.rules"
click node_ai_flows "https://github.com/diwascha/starweb/tree/main/src/ai/flows"
click node_google_sheets "https://github.com/diwascha/starweb/blob/main/src/services/google-sheets-service.ts"
click node_tauri_shell "https://github.com/diwascha/starweb/tree/main/src-tauri"

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_app_router,node_app_shell,node_sidebar,node_ui_primitives,node_shared_hooks toneBlue
class node_hr_module,node_fleet_module,node_finance_module,node_po_module,node_crm_module,node_reporting_module,node_notes_module toneAmber
class node_core_services,node_document_services,node_ops_services toneMint
class node_firebase_layer,node_firestore_rules,node_ai_flows,node_google_sheets toneRose
class node_tauri_shell toneIndigo
```

## Components

### App Shell

Next.js routes, navigation, and shared UI composition

- [App Router](https://github.com/diwascha/starweb/tree/main/src/app): nextjs routes · Main application entry and route hierarchy under src/app · `src/app`
- [App Shell](https://github.com/diwascha/starweb/blob/main/src/components/auth-aware-layout.tsx): layout/nav · Authenticated layout and global navigation shell · `src/components/auth-aware-layout.tsx`
- [Sidebar](https://github.com/diwascha/starweb/blob/main/src/components/app-sidebar.tsx): navigation · Primary module navigation for the workspace · `src/components/app-sidebar.tsx`
- [UI Primitives](https://github.com/diwascha/starweb/tree/main/src/components/ui): shadcn ui · Shared component library for forms, dialogs, tables, and controls · `src/components/ui`
- [Shared Hooks](https://github.com/diwascha/starweb/tree/main/src/hooks): client hooks · Cross-cutting UI hooks for auth, connection, mobile, and toasts · `src/hooks`

### Domain Workflows

Operational modules exposed through the app router

- [HR](https://github.com/diwascha/starweb/tree/main/src/app/hr): domain module · Employees, attendance, payroll, bonus, analytics, and payslips · `src/app/hr`
- [Fleet](https://github.com/diwascha/starweb/tree/main/src/app/fleet): domain module · Vehicles, drivers, trip sheets, and transaction workflows · `src/app/fleet`
- [Finance](https://github.com/diwascha/starweb/tree/main/src/app/finance): domain module · Cheques, estimate invoices, and tax calculation tools · `src/app/finance`
- [Purchase Orders](https://github.com/diwascha/starweb/tree/main/src/app/purchase-orders): workflow module · Create, edit, list, and view purchase orders · `src/app/purchase-orders`
- [CRM / Cost Reports](https://github.com/diwascha/starweb/tree/main/src/app/crm): workflow module · Cost reports, quotations, and packing/spec workflows · `src/app/crm`
- [Reporting](https://github.com/diwascha/starweb/tree/main/src/app/reports): domain module · Reports, dashboards, and report editing flows · `src/app/reports`
- [Notes](https://github.com/diwascha/starweb/tree/main/src/app/notes): workspace module · Simple notes workspace within the authenticated app · `src/app/notes`

### Services

Business logic and data access boundary

- [Core Services](https://github.com/diwascha/starweb/tree/main/src/services): service layer · Domain services for employees, payroll, attendance, products, and settings · `src/services`
- [Document Services](https://github.com/diwascha/starweb/tree/main/src/services): service layer · Services for purchase orders, reports, cheques, invoices, and trip documents · `src/services`
- [Ops Services](https://github.com/diwascha/starweb/tree/main/src/services): service layer · Fleet, finance, storage, backup, and usage services · `src/services`

### Platform

Firebase, AI, and external integration layers

- [Firebase](https://github.com/diwascha/starweb/tree/main/src/firebase): backend platform · Client providers and configuration for Firestore and Realtime Database · `src/firebase`
- [Rules](https://github.com/diwascha/starweb/blob/main/firestore.rules): security rules · Firestore security boundary for application data · `firestore.rules`
- [AI Flows](https://github.com/diwascha/starweb/tree/main/src/ai/flows): genkit flows · Genkit flows for translation and purchase-order summarization · `src/ai/flows`
- [Sheets Sync](https://github.com/diwascha/starweb/blob/main/src/services/google-sheets-service.ts): integration · External Google Sheets integration for export or sync workflows · `src/services/google-sheets-service.ts`

### Desktop

Tauri packaging for native delivery

- [Tauri Shell](https://github.com/diwascha/starweb/tree/main/src-tauri): desktop runtime · Native desktop packaging and shell configuration · `src-tauri`

## Connections

- App Router → App Shell: renders · Routes compose the authenticated shell and shared layout
- App Shell → Sidebar: includes · The shell uses the main workspace navigation
- App Shell → UI Primitives: builds with · Layout and screens are composed from shared UI primitives
- App Shell → Shared Hooks: uses · Authentication, connection, and viewport state drive the shell
- HR → Core Services: reads/writes · HR screens use employee, attendance, payroll, and user services
- Fleet → Ops Services: reads/writes · Fleet workflows use vehicle, driver, trip, and transaction services
- Finance → Document Services: renders via · Finance document workflows rely on cheque and invoice services
- Purchase Orders → Document Services: reads/writes · Purchase order CRUD and printable views use purchase-order services
- CRM / Cost Reports → Document Services: reads/writes · CRM cost-report and quotation screens use report and cost-report services
- Reporting → Document Services: reads/writes · Reporting pages use report-related services and dashboards
- Notes → Core Services: reads/writes · Notes features use notes service and shared data utilities
- Core Services → Firebase: persists to · Core business data is stored through Firebase clients
- Document Services → Firebase: persists to · Document-oriented workflows read and write Firebase data
- Ops Services → Firebase: persists to · Operational services use Firebase as the primary backend
- Firebase → Rules: governed by · Firestore access is constrained by repository-defined rules
- AI Flows → Core Services: augments · AI capabilities complement business workflows rather than replacing them
- AI Flows → Firebase: consumes data · AI flows can derive context from application records
- Sheets Sync → Ops Services: integrates with · Sheets sync is used by operational export or archive workflows
- Tauri Shell → App Router: packages · The same frontend runs in browser and desktop delivery modes