# p-thavamani/complaint-management-system architecture

> Architecture diagram of the GitHub repository p-thavamani/complaint-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p-thavamani/complaint-management-system
- Repository: https://github.com/p-thavamani/complaint-management-system

## Overview

##### Project type and purpose
- This is a full-stack web application: a Complaint Management System with AI-powered chatbot integration, ticketing, real-time tracking and admin dashboard.
- Frontend: React.js single-page application (SPA) using Hooks, Context API, TailwindCSS, Chart.js, React Router.
- Backend: Flask RESTful API with JWT authentication, scheduled tasks, and integrations (Google Speech-to-Text, YOLOv8 image analysis, Google Gemini).

##### File structure
- Top-level directories:
- frontend/ – React code, build config, public assets
- backend/ – Flask API modules, utilities, environment config, startup scripts
- backend/api/ contains endpoint modules (auth, users, complaints, chatbot, rewards, feedback, admin).
- backend/utils/ contains middleware, model downloads, notifications, scheduled-task helpers.
- frontend/src/components/, pages/, context/, services/ indicate UI components, routes, global state (AuthContext), and API client (axios).
- Configuration files: .env, package.json, requirements.txt, config-overrides.js, tailwind.config.js.

##### README insights
- Describes core and unique features, tech stack, DB (MongoDB Atlas), environment variables, setup steps.
- Mentions high-level architecture: frontend ↔ API ↔ database + external AI/image services.

a. Main components
- User-facing UI: React SPA (components, pages)
- API Layer: Flask RESTful app (app.py, run.py, api/*)
- Database: MongoDB Atlas (collections for users, complaints, tickets, rewards, feedback)
- Authentication: JWT handling via auth.py + auth_middleware
- Scheduled Tasks: scheduled_tasks.py for notifications, escalations, cleanup
- External Services:
– Google Speech-to-Text API (voice→text)
– YOLOv8 model server or library (image analysis)
– Google Gemini API (chatbot intelligence)
– Notification channels (email/SMS via notifications util)
b. Relationships and interactions
- React SPA sends HTTP/HTTPS requests to Flask API
- API verifies JWT, routes to appropriate api/*.py handlers
- Handlers perform CRUD on MongoDB via Flask drivers
- For voice/image complaints: handlers call Google Speech or YOLO modules in utils
- For chatbot sessions: api/chatbot.py communicates with Google Gemini
- Scheduled tasks trigger background workflows (daily summary, escalations)
- API emits real-time updates via WebSockets or polling (if implemented)
c. Architectural patterns and principles
- Layered architecture: Presentation (UI) → API (controllers) → Services/Utils → Data Layer
- Modular design: separate modules for each domain (auth, complaints, rewards)
- Middleware for cross-cutting concerns (auth_middleware)
- External integration abstraction in utils/download_model, test_speech, notifications
d. Key technologies
- React.js, TailwindCSS, Chart.js, React Router
- Flask, Flask-RESTful, PyMongo
- JWT (pyjwt), dotenv for config
- MongoDB Atlas
- Google Speech-to-Text API, YOLOv8, Google Gemini API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (UI Layer)"
        direction TB
        ReactSPA["React SPA"]:::ui
        IndexJS["index.js"]:::ui
        AppJS["App.js"]:::ui
        Components["UI Components"]:::ui
        Pages["Pages / Routes"]:::ui
        AuthContext["AuthContext"]:::ui
        AxiosClient["API Client (axios)"]:::ui
    end

    %% Backend Layer
    subgraph "Backend (Flask API)"
        direction TB
        FlaskAPI["Flask API"]:::api
        AppPY["app.py"]:::api
        RunPY["run.py"]:::api

        subgraph "API Endpoints"
            direction TB
            AuthEP["auth.py"]:::api
            UsersEP["users.py"]:::api
            ComplaintsEP["complaints.py"]:::api
            ComplaintsUpEP["complaints_updates.py"]:::api
            ChatbotEP["chatbot.py"]:::api
            FeedbackEP["feedback.py"]:::api
            RewardsEP["rewards.py"]:::api
            AdminEP["admin.py"]:::api
            CategoriesEP["categories.py"]:::api
        end

        subgraph "Utils & Integration"
            direction TB
            AuthMW["auth_middleware.py"]:::api
            DownloadModel["download_model.py"]:::api
            SpeechUtil["test_speech.py"]:::api
            YOLOUtil["test_yolo.py"]:::api
            GeminiUtil["test_gemini.py"]:::api
            NotifyUtil["notifications.py"]:::api
            RewardsUtil["rewards.py"]:::api
        end

        ScheduledTasks["scheduled_tasks.py"]:::bg
    end

    %% Database and External Services
    MongoDB["MongoDB Atlas"]:::db
    SpeechAPI["Google Speech-to-Text"]:::ext
    YOLOService["YOLOv8 Image Analysis"]:::ext
    GeminiAPI["Google Gemini API"]:::ext
    NotificationChan["Email/SMS Notifications"]:::ext

    %% Connections Frontend to Backend
    ReactSPA -->|"HTTPS/JSON"| FlaskAPI

    ReactSPA --> IndexJS
    ReactSPA --> AppJS
    ReactSPA --> Components
    ReactSPA --> Pages
    ReactSPA --> AuthContext
    ReactSPA --> AxiosClient

    %% Backend internals
    FlaskAPI --> AppPY
    FlaskAPI --> RunPY
    FlaskAPI --> AuthEP
    FlaskAPI --> UsersEP
    FlaskAPI --> ComplaintsEP
    FlaskAPI --> ComplaintsUpEP
    FlaskAPI --> ChatbotEP
    FlaskAPI --> FeedbackEP
    FlaskAPI --> RewardsEP
    FlaskAPI --> AdminEP
    FlaskAPI --> CategoriesEP

    FlaskAPI --> AuthMW
    FlaskAPI --> DownloadModel
    FlaskAPI --> SpeechUtil
    FlaskAPI --> YOLOUtil
    FlaskAPI --> GeminiUtil
    FlaskAPI --> NotifyUtil
    FlaskAPI --> RewardsUtil

    FlaskAPI --> ScheduledTasks
    ScheduledTasks --> NotifyUtil
    ScheduledTasks --> MongoDB

    %% Data flows
    AuthEP -->|CRUD| MongoDB
    UsersEP -->|CRUD| MongoDB
    ComplaintsEP -->|CRUD| MongoDB
    ComplaintsUpEP -->|CRUD| MongoDB
    FeedbackEP -->|CRUD| MongoDB
    RewardsEP -->|CRUD| MongoDB
    AdminEP -->|CRUD| MongoDB
    CategoriesEP -->|CRUD| MongoDB

    ComplaintsEP --> SpeechUtil
    ComplaintsEP --> YOLOUtil
    ChatbotEP --> GeminiUtil

    NotifyUtil --> NotificationChan

    %% External integrations
    SpeechUtil --> SpeechAPI
    YOLOUtil --> YOLOService
    GeminiUtil --> GeminiAPI

    %% Database
    FlaskAPI --> MongoDB

    %% Click events - Frontend
    click ReactSPA "https://github.com/p-thavamani/complaint-management-system/tree/main/frontend/src/"
    click IndexJS "https://github.com/p-thavamani/complaint-management-system/blob/main/frontend/src/index.js"
    click AppJS "https://github.com/p-thavamani/complaint-management-system/blob/main/frontend/src/App.js"
    click Components "https://github.com/p-thavamani/complaint-management-system/tree/main/frontend/src/components/"
    click Pages "https://github.com/p-thavamani/complaint-management-system/tree/main/frontend/src/pages/"
    click AuthContext "https://github.com/p-thavamani/complaint-management-system/blob/main/frontend/src/context/AuthContext.js"
    click AxiosClient "https://github.com/p-thavamani/complaint-management-system/blob/main/frontend/src/services/axios.js"

    %% Click events - Backend
    click AppPY "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/app.py"
    click RunPY "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/run.py"
    click AuthEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/auth.py"
    click UsersEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/users.py"
    click ComplaintsEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/complaints.py"
    click ComplaintsUpEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/complaints_updates.py"
    click ChatbotEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/chatbot.py"
    click FeedbackEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/feedback.py"
    click RewardsEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/rewards.py"
    click AdminEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/admin.py"
    click CategoriesEP "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/api/categories.py"
    click AuthMW "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/auth_middleware.py"
    click DownloadModel "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/download_model.py"
    click SpeechUtil "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/test_speech.py"
    click YOLOUtil "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/test_yolo.py"
    click GeminiUtil "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/test_gemini.py"
    click NotifyUtil "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/notifications.py"
    click RewardsUtil "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/utils/rewards.py"
    click ScheduledTasks "https://github.com/p-thavamani/complaint-management-system/blob/main/backend/scheduled_tasks.py"

    %% Styling
    classDef ui fill:#cce5ff,stroke:#1f77b4
    classDef api fill:#d4edda,stroke:#2ca02c
    classDef db fill:#fff3cd,stroke:#ff7f0e
    classDef ext fill:#f8d7da,stroke:#d62728
    classDef bg fill:#e2e3e5,stroke:#7f7f7f,stroke-dasharray: 5 5
```
