# thykp/oop_project architecture

> Architecture diagram of the GitHub repository thykp/oop_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thykp/oop_project
- Repository: https://github.com/thykp/oop_project

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“SingHealth Clinic Management System”) with a React/Vite frontend and a Spring Boot monolith backend.
- It supports three roles (Patient, Staff, Administrator), real-time updates (WebSocket/SSE), queue management (Kafka + Redis), persistent storage (relational database via JPA), and file storage (Supabase).

##### File Structure (Top-Level Components)
- frontend/ – React + TypeScript UI, Vite build, Supabase + WebSocket clients.
- backend/ – Spring Boot monolith, organized by packages: config, controller, service, repository, model, dto, util.
- database/ – SQL migration scripts for Postgres (or your chosen RDBMS).
- docker-compose.yml – orchestrates backend dependencies: Kafka, Zookeeper, Redis, database.

##### README for Architecture Insights
- REST API endpoints (controllers) exposed on port 8080.
- Asynchronous event streams:
- Kafka topics for queue events & notifications
- Redis queues & SSE streams for clinic queues
- WebSocket config for real-time updates
- Supabase for file/treatment-note storage.
- SecurityConfig for role-based access.

##### Main Components and Their Interactions
A. User Interface Layer (Browser/React Client)
- Pages & reusable UI components
- Uses REST calls (HTTP/HTTPS) and WebSockets/SSE
B. API Layer (Spring Boot Controllers)
- AuthController, AppointmentController, QueueControllers, etc.
- Exposes RESTful endpoints => documented in Swagger/OpenAPI (if enabled)
C. Business Logic Layer (Services)
- AppointmentService, QueueSseService, KafkaProducer/Consumer services, Notification services, SupabaseStorageService
D. Data Access Layer (Repositories)
- JPA repositories for Appointment, User, Clinic, TimeSlot, TreatmentNote, etc.
E. Database (Relational DB)
- Stores entities; migrations under database/migrations
F. Message Brokers & Caches
- Kafka cluster: topics for queue events & notifications
- Redis: per-clinic queues, SSE state (clinic:*:queue, clinic:*:nowServing)
G. File Storage / External Services
- Supabase Storage for treatment note attachments
- External email service (SMTP) via NotificationEmailConsumer
H. Real-Time Channels
- WebSocket endpoints for push notifications
- Server-Sent Events (SSE) for queue updates

##### Relationships & Data Flows
1. User → Frontend (UI interactions)
2. Frontend → Backend (REST API calls for login, booking, check-in, reports… )
3. Backend → Database (CRUD operations via repositories)
4. Backend → Kafka (publish queue events, notification events)
5. Kafka → Backend (consumers processing events)
6. Backend → Redis (enqueue/dequeue patient in queue streams)
7. Backend → Supabase (upload/download treatment note files)
8. Backend → WebSocket/SSE → Frontend (real-time updates)
9. Backend → SMTP / Email Service (email notifications)

##### Architectural Patterns
- Layered architecture (Controller → Service → Repository)
- Event-driven integration (Kafka producers/consumers, Redis queues, SSE)
- Asynchronous config (AsyncConfig)
- Role-based security (SecurityConfig)
- Configuration via Spring Profiles (application.properties, application-prod.properties)

##### Technologies, Frameworks, Libraries
- Frontend: React, TypeScript, Vite, Supabase JS, native WebSocket/SSE
- Infrastructure: Docker Compose (Kafka, Zookeeper, Redis, Postgres), Maven wrapper

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Interface Layer
    subgraph "User Interface Layer" 
        direction TB
        UI["React UI<br/>(Vite, TypeScript)"]:::ui
        Pages["UI Pages"]:::ui
        Components["Reusable UI Components"]:::ui
        Libs["Supabase & WebSocket Clients"]:::ui
    end

    %% Backend API Layer
    subgraph "API Layer (Controllers)" 
        direction TB
        Controllers["Spring Boot Controllers"]:::backend
        WSController["QueueStreamController (WS/SSE)"]:::backend
        RedisController["RedisQueueController"]:::backend
    end

    %% Backend Internal Layers
    subgraph "Backend Internal" 
        direction TB
        subgraph "Configuration" 
            direction TB
            SecurityCfg["SecurityConfig"]:::backend
            AsyncCfg["AsyncConfig"]:::backend
            WebSocketCfg["WebSocketConfig"]:::backend
            SupabaseCfg["SupabaseConfig"]:::backend
            KafkaCfg["KafkaConfig"]:::backend
            RedisCfg["RedisConfig"]:::backend
        end
        subgraph "Services" 
            direction TB
            ApptSvc["AppointmentService"]:::backend
            QueueSseSvc["QueueSseService"]:::backend
            RedisQueueSvc["RedisQueueService"]:::backend
            SupabaseStorageSvc["SupabaseStorageService"]:::backend
            KafkaSvc["Kafka Producers/Consumers"]:::backend
            EmailConsumer["NotificationEmailConsumer"]:::backend
        end
        subgraph "Repositories" 
            direction TB
            Repos["JPA Repositories"]:::backend
        end
        subgraph "Models & DTOs" 
            direction TB
            Models["Domain Models"]:::backend
            DTOs["Data Transfer Objects"]:::backend
        end
    end

    %% Data Stores & Brokers
    subgraph "Data Stores & Brokers"
        direction TB
        DB["Postgres DB"]:::db
        Kafka["Kafka Cluster"]:::db
        Redis["Redis Cache"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SupabaseStore["Supabase Storage"]:::ext
        EmailService["SMTP Email Service"]:::ext
    end

    %% Infrastructure
    DockerCompose["docker-compose.yml"]:::ext
    Migrations["Database Migrations"]:::ext

    %% Connections - synchronous
    UI -->|"HTTP REST"| Controllers
    Pages --> UI
    Components --> UI
    Libs --> UI

    Controllers -->|"calls"| ApptSvc
    Controllers -->|"calls"| QueueSseSvc
    Controllers -->|"calls"| RedisQueueSvc

    ApptSvc -->|"CRUD via JPA"| Repos
    Repos -->|"reads/writes"| DB

    %% Asynchronous via Kafka
    ApptSvc -.->|"publish events"| Kafka
    Kafka -.->|"consume events"| KafkaSvc
    KafkaSvc -->|"process events"| ApptSvc

    %% Asynchronous via Redis
    QueueSseSvc -.->|"enqueue/dequeue"| Redis
    RedisQueueSvc -.->|"manage queues"| Redis

    %% File Storage
    SupabaseStorageSvc -->|"upload/download"| SupabaseStore

    %% Email notifications
    EmailConsumer -->|"send email"| EmailService

    %% Real-time to UI
    QueueSseSvc -->|"SSE"| Libs
    WSController -->|"WebSocket"| Libs

    %% Infrastructure links
    DockerCompose --> Kafka
    DockerCompose --> Redis
    DockerCompose --> DB
    Migrations --> DB

    %% Click Events
    click UI "https://github.com/thykp/oop_project/tree/main/frontend/"
    click Pages "https://github.com/thykp/oop_project/tree/main/frontend/src/pages/"
    click Components "https://github.com/thykp/oop_project/tree/main/frontend/src/components/"
    click Libs "https://github.com/thykp/oop_project/blob/main/frontend/src/lib/supabase.ts"
    click Libs "https://github.com/thykp/oop_project/blob/main/frontend/src/lib/socket.ts"
    click Controllers "https://github.com/thykp/oop_project/tree/main/backend/src/main/java/com/is442/backend/controller/"
    click WSController "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/controller/QueueStreamController.java"
    click RedisController "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/controller/RedisQueueController.java"
    click SecurityCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/SecurityConfig.java"
    click AsyncCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/AsyncConfig.java"
    click WebSocketCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/WebSocketConfig.java"
    click SupabaseCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/SupabaseConfig.java"
    click KafkaCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/KafkaConfig.java"
    click RedisCfg "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/config/RedisConfig.java"
    click ApptSvc "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/AppointmentService.java"
    click QueueSseSvc "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/QueueSseService.java"
    click RedisQueueSvc "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/RedisQueueService.java"
    click SupabaseStorageSvc "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/SupabaseStorageService.java"
    click KafkaSvc "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/KafkaQueueEventProducer.java"
    click EmailConsumer "https://github.com/thykp/oop_project/blob/main/backend/src/main/java/com/is442/backend/service/NotificationEmailConsumer.java"
    click Repos "https://github.com/thykp/oop_project/tree/main/backend/src/main/java/com/is442/backend/repository/"
    click Models "https://github.com/thykp/oop_project/tree/main/backend/src/main/java/com/is442/backend/model/"
    click DTOs "https://github.com/thykp/oop_project/tree/main/backend/src/main/java/com/is442/backend/dto/"
    click DockerCompose "https://github.com/thykp/oop_project/blob/main/docker-compose.yml"
    click Migrations "https://github.com/thykp/oop_project/tree/main/database/migrations/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef db fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef ext fill:#e0e0e0,stroke:#333,stroke-width:1px
```
