# mohamedgamal-ahmed/complaints-committee architecture

> Architecture diagram of the GitHub repository mohamedgamal-ahmed/complaints-committee, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamedgamal-ahmed/complaints-committee
- Repository: https://github.com/mohamedgamal-ahmed/complaints-committee

## Overview

##### نوع المشروع وهدفه (من الشجرة + الـ README)
- **النوع**: تطبيق Web Frontend (SPA) مبني بـ **React + Vite + TypeScript**، موجه للهواتف (Web-View).
- **الهدف**: “نظام إدارة شكاوى” لنادي المقاولون العرب:
- أعضاء: تسجيل/دخول، إنشاء شكوى، متابعة الحالة عبر **Timeline**، استلام ردود.
- إدارة/مسؤولين: لوحة تحكم تشمل **Analytics** ورسوم بيانية (**Recharts**)، إدارة شكاوى، اشتراكات، مستخدمين، إعلانات.
- **ملحوظة معمارية مهمة**: لا توجد في الشجرة أي مجلدات Backend أو API server. إذن هذا المستودع يمثل **واجهة العميل فقط** مع “Services” لطبقة منطق العمل/التكامل (قد تكون Mock أو استدعاءات API غير ظاهرة). لذلك الرسم المعماري الأفضل يجب أن يوضح:
- طبقات الـ UI داخل المتصفح
- طبقة الخدمات داخل العميل
- وخارج حدود المستودع: “Backend APIs / Database / Admin systems” كـ External dependencies (حتى لو غير موجودة فعلياً هنا).

##### نقاط الدخول والتجميع (Bootstrapping & Build)
- `index.html`, `index.tsx`, `App.tsx`, `vite.config.ts`, `tsconfig.json`
- هذه تمثل **طبقة runtime في المتصفح** + **build pipeline** (Vite bundling).

##### UI Components (واجهة المستخدم)
- `src/components/*`
- Views/Dashboards:
- `LoginView.tsx`, `RegisterView.tsx`
- `MemberDashboard.tsx`, `StaffDashboard.tsx`, `AdminDashboard.tsx`
- شكاوى:
- `NewComplaint.tsx`, `Timeline.tsx`
- Admin area (Tabs):
- `src/components/Admin/*Tab.tsx`: Analytics, Announcements, Complaints, Subscriptions, Users
- Shared:
- `Common.tsx`

**استنتاج**: الواجهة مقسمة حسب **أدوار المستخدم** (Member/Staff/Admin) + تقسيم داخل الإدارة إلى Tabs. هذا مهم لإبرازه في الرسم كـ “Modules”.

##### Services (Business Logic / Integration)
- `src/services/AuthService.ts`
- `src/services/ComplaintService.ts`

**استنتاج**: يوجد فصل واضح بين:
- طبقة العرض (Components)
- وطبقة منطق الأعمال/التعامل مع البيانات (Services)

حتى لو كانت هذه الخدمات حالياً Local أو تعتمد على constants، فمعمارياً تُعامل كـ **Client-side domain services**.

##### Types + Constants
- `src/types/index.ts`
- `src/constants/index.ts`

**استنتاج**: وجود “Contracts” (Types) و”Config/Seed data” (Constants). في الرسم، اجعلها كـ Supporting modules للـ Services والـ UI.

##### ما الذي يجب أن يمثّله الرسم المعماري لهذا المشروع تحديداً؟
بما أنه SPA للهواتف (WebView) وبلا Backend داخل repo:

أفضل نتيجة عادة تكون رسمين (أو صفحة واحدة بها مستويين):
1) **C4 Level 2 (Container-ish)** لكن هنا “Container” واحد رئيسي (Web App) + External Systems.

##### Client / WebView Runtime (داخل الهاتف)
- **WebView Host** (Mobile container) ← يحمّل
- **React SPA (Vite bundle)**

داخل React SPA قسّم إلى:
##### Entry & Shell
- `index.tsx` (mount)
- `App.tsx` (App shell / routing إن وجد أو state root)
##### UI Layer (Components)
- Auth Views: `LoginView`, `RegisterView`
- Dashboards:
- Member: `MemberDashboard` + (`NewComplaint`, `Timeline`)
- Staff: `StaffDashboard`
- Admin: `AdminDashboard` + Admin Tabs:
- `AnalyticsTab` (Recharts)
- `ComplaintsTab`
- `UsersTab`
- `SubscriptionsTab`
- `AnnouncementsTab`
- Shared: `Common`
##### Domain/Service Layer
- `AuthService` (authentication/session/roles)
- `ComplaintService` (CRUD complaints, status updates, timeline data)
##### Data Contracts & Config
- `types/*`
- `constants/*`

##### External/Out-of-Repo Systems (ضعها كـ “Assumed”)
حتى لو غير مذكورة صراحة، هذا النوع من الأنظمة يحتاج عادة:
- **Backend API** (Auth/Complaints/Admin endpoints)
- **Database** (Users, Complaints, Subscriptions, Announcements)
- (اختياري حسب المنتج) **Notification service** (Push/SMS/Email)

في الرسم اكتب بوضوح “External (not in this repo)” لتجنب التباس.

##### العلاقات والتفاعلات التي يجب رسمها (Data flow)
ارسم الأسهم كـ “calls/uses/depends on”:

##### Auth flow
- `LoginView/RegisterView` → `AuthService`
- `AuthService` → (External) `Auth API`
- `AuthService` → (Local) `types` (UserRole, AuthResponse…)
- `AuthService` → (Local) Storage (LocalStorage/SessionStorage) **إن كان موجوداً** (إن لم يكن واضحاً في الكود، اتركها كـ “Client Storage (optional)”)

##### Complaints flow (Member)
- `NewComplaint` → `ComplaintService` → (External) `Complaints API`
- `Timeline` / `MemberDashboard` → `ComplaintService` → fetch list/status history

##### Admin flows
- `AdminDashboard` → Tabs
- `ComplaintsTab/UsersTab/...` → `ComplaintService` أو `AuthService` (حسب العمليات)
- `AnalyticsTab` → (Data provider: `ComplaintService`) → يعرض عبر **Recharts**

##### Constants usage
- Components/Services → `constants/index.ts` (seed data, UI constants)
ضع سهم “reads from” وليس “calls”.

##### الأنماط/المبادئ المعمارية الظاهرة والتي يجب توضيحها
- **Separation of Concerns** (مذكورة في README ومطبقة بالمجلدات):
- Components = presentation
- Services = business logic/integration
- Types = contracts
- Constants = config/mock
- **Role-based UI modules**:
- Member vs Staff vs Admin
- **Tabbed Admin module** كـ sub-components داخل AdminDashboard
- **Client-side “Service layer”** (يشبه Facade/Adapter) لعزل الـ UI عن مصدر البيانات (API أو mock).

##### الخطوة 1: ارسم حدود النظام
- مربع كبير بعنوان: **Arab Contractors Club Complaints System – Web App (React/Vite/TS)**
- خارج المربع: WebView Host + External APIs/DB

##### الخطوة 2: داخل مربع الـ Web App ارسم طبقات واضحة
استخدم 4 صفوف أو 4 مجموعات:

##### الخطوة 3: في UI layer لا تكتفي بـ “Components”
قسّمها حسب الهيكل الفعلي:
- Auth (Login/Register)
- Member module (Dashboard + NewComplaint + Timeline)
- Staff module (Dashboard)
- Admin module (Dashboard + Tabs…)
- Shared (Common)

##### الخطوة 4: اربط كل module بالخدمات التي يستخدمها
- Auth module → AuthService
- Complaint-related UI → ComplaintService
- Admin tabs → ComplaintService (+ AuthService عند الحاجة)

##### الخطوة 5: ضع External systems بأسهم واضحة
- Services → Backend API
- Backend API → Database
- (Optional) Backend API → Notifications

##### عناصر إلزامية في الرسم (كما تريد لمستوى Principal)
- **Labels دقيقة** بأسماء حقيقية من المشروع (AuthService, ComplaintService, AdminDashboard, AnalyticsTab…).
- UI → Services
- Services → External APIs
- External API → DB
- **ملاحظة تقنية** على الرسم: “React + Vite + Tailwind + TypeScript, Recharts (Analytics)”.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Context
  %% =========================
  subgraph EXT["External (not in this repo)"]
    direction TB
    WebView["Mobile WebView Host"]:::external
    BackendAPI["Backend API\n(Auth / Complaints / Admin endpoints)"]:::external
    DB[("Database\n(Users / Complaints / Subscriptions / Announcements)")]:::external
    Notif["Notification Service\n(Push/SMS/Email) (optional)"]:::external
  end

  %% =========================
  %% System Boundary (Client)
  %% =========================
  subgraph SYS["Arab Contractors Club Complaints System — Web App (React + Vite + TypeScript)"]
    direction TB

    subgraph BOOT["Bootstrapping & Build"]
      direction TB
      HTML["index.html\n(HTML entry point)"]:::build
      ViteCfg["vite.config.ts\n(Vite bundling config)"]:::build
      TSCfg["tsconfig.json\n(TypeScript config)"]:::build
      Entry["index.tsx\n(Mount React app)"]:::runtime
      App["App.tsx\n(App shell / root)"]:::runtime
    end

    subgraph UI["UI Layer — Components (Role-based modules)"]
      direction TB

      ComponentsDir["src/components/\n(Components directory)"]:::supportAlt

      subgraph AUTHV["Auth Views"]
        direction TB
        Login["LoginView.tsx"]:::ui
        Register["RegisterView.tsx"]:::ui
      end

      subgraph MEMBER["Member Module"]
        direction TB
        MemberDash["MemberDashboard.tsx"]:::ui
        NewComplaint["NewComplaint.tsx"]:::ui
        Timeline["Timeline.tsx"]:::ui
      end

      subgraph STAFF["Staff Module"]
        direction TB
        StaffDash["StaffDashboard.tsx"]:::ui
      end

      subgraph ADMIN["Admin Module"]
        direction TB
        AdminDash["AdminDashboard.tsx"]:::ui

        subgraph ADMINTABS["Admin Tabs"]
          direction TB
          AnalyticsTab["AnalyticsTab.tsx\n(Charts via Recharts)"]:::ui
          ComplaintsTab["ComplaintsTab.tsx"]:::ui
          UsersTab["UsersTab.tsx"]:::ui
          SubscriptionsTab["SubscriptionsTab.tsx"]:::ui
          AnnouncementsTab["AnnouncementsTab.tsx"]:::ui
        end
      end

      SharedCommon["Common.tsx\n(Shared UI)"]:::uiShared
    end

    subgraph DOMAIN["Domain / Service Layer (Client-side business logic & integration)"]
      direction TB
      ServicesDir["src/services/\n(Services directory)"]:::supportAlt
      AuthService["AuthService.ts\n(Authentication / Session / Roles)"]:::service
      ComplaintService["ComplaintService.ts\n(Complaints CRUD / Status / Timeline)"]:::service
    end

    subgraph SUPPORT["Supporting Modules"]
      direction TB
      Types["types/index.ts\n(Data contracts)"]:::support
      Constants["constants/index.ts\n(Config / Seed / Mock data)"]:::support
      ClientStorage["Client Storage\n(LocalStorage/SessionStorage) (optional)"]:::supportAlt
    end

    subgraph LEGEND["Legend"]
      direction TB
      L1["UI Components"]:::ui
      L2["Services"]:::service
      L3["Types & Constants"]:::support
      L4["External systems"]:::external
      L5["Build/Runtime"]:::build
    end
  end

  %% =========================
  %% Relationships (Vertical-first)
  %% =========================
  WebView -->|"loads"| HTML
  HTML -->|"boots"| Entry
  Entry -->|"renders"| App

  App -->|"routes/hosts"| Login
  App -->|"routes/hosts"| Register
  App -->|"routes/hosts"| MemberDash
  App -->|"routes/hosts"| StaffDash
  App -->|"routes/hosts"| AdminDash

  AdminDash -->|"contains"| AnalyticsTab
  AdminDash -->|"contains"| ComplaintsTab
  AdminDash -->|"contains"| UsersTab
  AdminDash -->|"contains"| SubscriptionsTab
  AdminDash -->|"contains"| AnnouncementsTab

  MemberDash -->|"contains"| NewComplaint
  MemberDash -->|"contains"| Timeline

  %% Auth flow
  Login -->|"calls"| AuthService
  Register -->|"calls"| AuthService
  AuthService -->|"calls"| BackendAPI
  AuthService -.->|"uses"| Types
  AuthService -.->|"reads"| Constants
  AuthService -.->|"stores (optional)"| ClientStorage

  %% Complaints flow
  NewComplaint -->|"calls"| ComplaintService
  Timeline -->|"calls"| ComplaintService
  MemberDash -->|"calls"| ComplaintService

  ComplaintService -->|"calls"| BackendAPI
  ComplaintService -.->|"uses"| Types
  ComplaintService -.->|"reads"| Constants

  %% Admin flows
  AnalyticsTab -->|"gets_data"| ComplaintService
  ComplaintsTab -->|"calls"| ComplaintService
  UsersTab -->|"calls"| AuthService
  SubscriptionsTab -->|"calls"| AuthService
  AnnouncementsTab -->|"calls"| AuthService

  %% External dependencies
  BackendAPI -->|"persists/reads"| DB
  BackendAPI -.->|"sends (optional)"| Notif

  %% Build-time associations (kept minimal)
  ViteCfg -.->|"builds"| HTML
  ViteCfg -.->|"bundles"| Entry
  TSCfg -.->|"typechecks"| Entry
  TSCfg -.->|"typechecks"| App

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Entry "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/index.tsx"
  click App "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/App.tsx"
  click HTML "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/index.html"
  click ViteCfg "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/vite.config.ts"
  click TSCfg "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/tsconfig.json"

  click Login "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/LoginView.tsx"
  click Register "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/RegisterView.tsx"
  click MemberDash "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/MemberDashboard.tsx"
  click NewComplaint "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/NewComplaint.tsx"
  click Timeline "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Timeline.tsx"
  click StaffDash "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/StaffDashboard.tsx"
  click AdminDash "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/AdminDashboard.tsx"

  click AnalyticsTab "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Admin/AnalyticsTab.tsx"
  click ComplaintsTab "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Admin/ComplaintsTab.tsx"
  click UsersTab "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Admin/UsersTab.tsx"
  click SubscriptionsTab "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Admin/SubscriptionsTab.tsx"
  click AnnouncementsTab "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Admin/AnnouncementsTab.tsx"

  click SharedCommon "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/components/Common.tsx"
  click AuthService "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/services/AuthService.ts"
  click ComplaintService "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/services/ComplaintService.ts"
  click Types "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/types/index.ts"
  click Constants "https://github.com/mohamedgamal-ahmed/complaints-committee/blob/main/src/constants/index.ts"

  %% Directories
  click ComponentsDir "https://github.com/mohamedgamal-ahmed/complaints-committee/tree/main/src/components/"
  click ServicesDir "https://github.com/mohamedgamal-ahmed/complaints-committee/tree/main/src/services/"

  %% =========================
  %% Styles
  %% =========================
  classDef ui fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1px
  classDef uiShared fill:#1565c0,stroke:#0d47a1,color:#ffffff,stroke-width:1px
  classDef service fill:#2e7d32,stroke:#1b5e20,color:#ffffff,stroke-width:1px
  classDef support fill:#616161,stroke:#424242,color:#ffffff,stroke-width:1px
  classDef supportAlt fill:#78909c,stroke:#546e7a,color:#ffffff,stroke-width:1px,stroke-dasharray:4 3
  classDef build fill:#6a1b9a,stroke:#4a148c,color:#ffffff,stroke-width:1px
  classDef runtime fill:#8e24aa,stroke:#4a148c,color:#ffffff,stroke-width:1px
  classDef external fill:#fb8c00,stroke:#e65100,color:#1b1b1b,stroke-width:1px,stroke-dasharray:6 4
```
