# pralayeshmukherjee/firefly architecture

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

- Interactive diagram: https://gitdiagram.com/pralayeshmukherjee/firefly
- Repository: https://github.com/pralayeshmukherjee/firefly

## Overview

##### Project Type and Purpose
- Type: Full-stack web application
- Frontend: React (Vite) + Tailwind CSS
- Backend: Spring Boot (Java + Maven)
- Database: MySQL
- AI Layer / External APIs: Google APIs (for location/auth) and a future Generative AI API (“GeminiAPI” service)
- Purpose: An AI-powered healthcare assistant offering symptom checking, doctor/hospital finder, medicine suggestions, and (soon) a generative chatbot.

##### File Structure
- Top level: two folders—FireFlyBackend and Frontend—plus root README and LICENSE.
- FireFlyBackend: Maven wrapper, pom.xml, standard Spring Boot layout under src/main/java:
– Config (CORS, Security)
– Controller (APIController, GoogleController, UserController)
– Service (UserService, CustomOAuth2UserService, GeminiAPI)
– DTO (AddUser, ChatRequest)
– Entity (UserEntity)
– Repository (UserRepository)
– resources/static (images, static assets)
- Frontend: Vite setup (vite.config.js), React source under src/:
– Components (Chatbot, Landing pages, Login, OTP, SignUp, ThemeBtn)
– Context (Theme state)
– Layout.jsx, App.jsx, main.jsx
– public/index.html, assets, CSS files

##### Extract Additional Insights from README
- Clearly separated tech stack: frontend/backend/database/AI.
- External dependencies: MySQL, Generative AI API (upcoming), Google services.
- Running ports: FE (5173), BE (8080).

a. Main Components
1. User’s Browser / Mobile Device
2. Frontend Web App (React + Tailwind)
3. Backend REST API (Spring Boot)
4. MySQL Database
5. External Services:
- Google Maps / Places API (via GoogleController)
- OAuth2 Provider (via CustomOAuth2UserService)
- Generative AI API (via GeminiAPI service)

b. Relationships & Data Flows
- Browser ↔ Frontend: HTTP(S) calls, user interactions, static asset serving
- Frontend → Backend: REST calls (login/signup, symptom data, doctor requests)
- Backend (Controller → Service → Repository) → MySQL: CRUD operations
- Backend → External Services:
– GoogleController calls Google Maps/Places
– CustomOAuth2UserService handles OAuth flows
– GeminiAPI calls Generative AI endpoints
- Responses flow back upstream (service → controller → frontend → user).

c. Architectural Patterns & Principles
- Layered architecture (Controller → Service → Repository)
- Separation of concerns: configuration classes for security/CORS
- Stateless REST APIs
- Context/State management on the frontend (React Context)
- Future extensibility: generative AI integration as a separate service layer

d. Key Technologies / Frameworks
- React + Vite + Tailwind
- Spring Boot + Maven
- MySQL (via spring-data JPA)
- OAuth2 (Spring Security)
- Google API SDK
- Generative AI (external HTTP client)

##### Detail Without Overthinking
- Future points of extension: the generative AI service, health record storage, mobile clients.
- If room permits, annotate configuration classes (CORS/Security) as side-modules to the REST API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    User["User's Browser/Mobile"]:::ui

    %% Frontend Zone
    subgraph "Frontend Layer"
        direction TB
        FEApp["Frontend Web App\n(React + Tailwind)"]:::frontend
        StaticHTML["Static HTML Entry Point"]:::frontend
        MainEntry["React App Entry (main.jsx)"]:::frontend
        Layout["Root Layout Component (Layout.jsx)"]:::frontend
        AppComp["App Component (App.jsx)"]:::frontend
        Components["React Components\n(Chatbot, Landing, Auth)"]:::frontend
        ThemeCtx["Theme Context (Theme.jsx)"]:::frontend
        ViteCfg["Vite Configuration"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend Layer"
        direction TB

        %% API Controllers
        subgraph "Controllers" 
            direction TB
            APIController["APIController.java"]:::controller
            GoogleController["GoogleController.java"]:::controller
            UserController["UserController.java"]:::controller
        end

        %% Service Layer
        subgraph "Services"
            direction TB
            UserService["UserService.java"]:::service
            OAuthService["CustomOAuth2UserService.java"]:::service
            GeminiService["GeminiAPI.java"]:::service
        end

        %% DTOs
        subgraph "DTOs"
            direction TB
            AddUserDTO["AddUser.java"]:::dto
            ChatReqDTO["ChatRequest.java"]:::dto
        end

        %% Entity
        UserEntity["UserEntity.java"]:::entity

        %% Repository
        UserRepo["UserRepository.java"]:::repository

        %% Config Modules
        subgraph "Configuration"
            direction TB
            CORSConfig["CORSConfig.java"]:::config
            SecurityConfig["SecurityConfig.java"]:::config
        end

        MainApp["FireFlyBackendApplication.java"]:::config
        StaticAssets["Static Assets\n(resources/static)"]:::frontend
    end

    %% Database
    MySQL[(MySQL Database)]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleMaps["Google Maps/Places API"]:::external
        OAuthProvider["OAuth2 Provider"]:::external
        GenAI["Generative AI API\n(Future - GeminiAPI)"]:::external
    end

    %% Connections
    User -->|Uses| FEApp
    FEApp -->|Serves| StaticHTML
    FEApp -->|Loads| MainEntry
    MainEntry -->|Renders| Layout
    Layout -->|Contains| AppComp
    AppComp -->|Uses| Components
    AppComp -->|Uses| ThemeCtx
    FEApp -->|Configured by| ViteCfg

    FEApp -->|REST Calls| APIController
    APIController -->|Invokes| UserService
    APIController -->|Invokes| OAuthService
    APIController -->|Invokes| GeminiService
    UserService -->|CRUD| UserRepo
    OAuthService -->|Handles OAuth| OAuthProvider
    GeminiService -->|Calls| GenAI
    UserService -->|Uses| AddUserDTO
    GeminiService -->|Uses| ChatReqDTO

    APIController -->|Loads| UserController
    APIController -->|Loads| GoogleController

    UserRepo -->|JDBC| MySQL
    MainApp -->|Bootstraps| APIController
    MainApp -->|Bootstraps| Service

    GoogleController -->|Calls| GoogleMaps

    %% Click Events
    click FEApp "https://github.com/pralayeshmukherjee/firefly/tree/master/Frontend/src"
    click StaticHTML "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/index.html"
    click MainEntry "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/src/main.jsx"
    click Layout "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/src/Layout.jsx"
    click AppComp "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/src/App.jsx"
    click Components "https://github.com/pralayeshmukherjee/firefly/tree/master/Frontend/src/Component"
    click ThemeCtx "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/src/Context/Theme.jsx"
    click ViteCfg "https://github.com/pralayeshmukherjee/firefly/blob/master/Frontend/vite.config.js"

    click MainApp "https://github.com/pralayeshmukherjee/firefly/blob/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/FireFlyBackendApplication.java"
    click APIController "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Controller"
    click GoogleController "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Controller"
    click UserController "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Controller"
    click UserService "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Service"
    click OAuthService "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Service"
    click GeminiService "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Service"
    click AddUserDTO "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/DTO"
    click ChatReqDTO "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/DTO"
    click UserEntity "https://github.com/pralayeshmukherjee/firefly/blob/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/entity/UserEntity.java"
    click UserRepo "https://github.com/pralayeshmukherjee/firefly/blob/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/repository/UserRepository.java"
    click CORSConfig "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Config"
    click SecurityConfig "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/java/com/backend/FireFlyBackend/Config"
    click StaticAssets "https://github.com/pralayeshmukherjee/firefly/tree/master/FireFlyBackend/src/main/resources/static"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef controller fill:#C8E6C9,stroke:#66BB6A,color:#1B5E20
    classDef service fill:#FFF9C4,stroke:#FDD835,color:#F57F17
    classDef repository fill:#FFE0B2,stroke:#FFB74D,color:#E65100
    classDef config fill:#E1BEE7,stroke:#BA68C8,color:#4A148C
    classDef entity fill:#FFCCBC,stroke:#FF8A65,color:#BF360C
    classDef dto fill:#F5F5F5,stroke:#BDBDBD,color:#424242
    classDef database fill:#BBDEFB,stroke:#42A5F5,color:#0D47A1
    classDef external fill:#CFD8DC,stroke:#90A4AE,color:#37474F
    classDef ui fill:#B3E5FC,stroke:#29B6F6,color:#01579B
```
