# vatsalgandhi83/sj-hopes architecture

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

- Interactive diagram: https://gitdiagram.com/vatsalgandhi83/sj-hopes
- Repository: https://github.com/vatsalgandhi83/sj-hopes

## Overview

##### Project type and purpose
- SJ Hopes is a full-stack web application built for managing homelessness services (shelter availability, client casework, work opportunities, admin analytics).
- It consists of a React/Next.js frontend, a Spring Boot backend, and a relational database (MySQL/PostgreSQL).

##### File structure
- Top‐level directories:
– /backend/sjHopes → Spring Boot project (Gradle, Java 17+, layered MVC pattern)
– /frontend → Next.js/React application (TypeScript, MUI, Google Maps integration)
– /backend/sql/sample-data → raw SQL scripts for sample data
- Backend layering:
– src/main/java/com/sjhacks/sjhopes/controller → HTTP controllers (REST endpoints)
– mapper → DTO ↔ entity conversion
– service → business logic interfaces & implementations
– repository → Spring Data JPA repositories
– models/entity & models/dto → persistence models and API payloads
- Key config files: application.properties (datasource, JPA), Swagger/OpenAPI, Gradle wrapper.
- Frontend structure:
– src/app → Next.js “app router” pages (admin, clients, opportunities, shelters, tasks)
– src/api → Axios wrappers for REST endpoints
– src/components → reusable UI (modals, cards, maps, sections)
– src/hooks/useAuth.ts → authentication context
– public/images, globals.css, next.config.js, tsconfig.json.

##### README for additional insights
- Role-based access (public, caseworker, admin) drives conditional UI flows.
- Uses Springdoc OpenAPI to expose Swagger UI.
- Google Maps API for real-time shelter map.
- MySQL (or PostgreSQL) as primary datastore.

##### Detail
- Package-level breakdown if needed (e.g., controller vs service packages).
- Interactions like JWT/session auth if implemented.
- Data flow for key use cases: shelter search, client registration, task assignment, analytics retrieval.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Users"
        direction TB
        Public("Public User"):::users
        Caseworker("Caseworker"):::users
        Admin("Administrator"):::users
    end

    subgraph "Frontend (Next.js)" 
        direction TB
        UI("Next.js Frontend"):::frontend
        APIWrappers("API Wrappers (Axios)"):::frontend
        Components("UI Components"):::frontend
        AuthHook("Auth Context"):::frontend
        MapComp("ShelterMap Component"):::frontend
        Styles("Global Styles & Config"):::frontend
        UI --> APIWrappers
        UI --> Components
        UI --> AuthHook
        Components --> MapComp
        UI --> Styles
    end

    Public -->|"interact/authenticate"| UI
    Caseworker -->|"interact/authenticate"| UI
    Admin -->|"interact/authenticate"| UI

    subgraph "Backend (Spring Boot)"
        direction TB
        MainApp("SjHopesApplication"):::backend

        subgraph Controllers
            direction TB
            AdminCtrl("AdminController"):::controller
            ClientCtrl("ClientController"):::controller
            ResourceCtrl("ResourceController"):::controller
            TaskCtrl("TaskController"):::controller
        end

        subgraph Services
            direction TB
            AnalyticsSvc("AnalyticsServiceImpl"):::service
            ClientSvc("ClientServiceImpl"):::service
            ResourceSvc("ResourceServiceImpl"):::service
            TaskSvc("TaskServiceImpl"):::service
        end

        subgraph Repositories
            direction TB
            ClientRepo("ClientRepository"):::repo
            ShelterRepo("ShelterRepository"):::repo
            TaskRepo("TaskRepository"):::repo
        end

        subgraph Mappers
            direction TB
            ClientMapper("ClientMapper"):::mapper
            ShelterMapper("ShelterMapper"):::mapper
            TaskMapper("TaskMapper"):::mapper
        end

        subgraph "Models"
            direction TB
            Entity("Persistence Models"):::model
            DTO("API Models (DTOs)"):::model
        end

        Config("application.properties"):::config
        API_Docs("Swagger UI"):::external

        MainApp --> Controllers
        Controllers --> Services
        Services --> Repositories
        Repositories --> Entity
        DTO --> Mappers --> Entity
        MainApp --> Config
        MainApp --> API_Docs
    end

    UI -->|"HTTPS Calls"| AdminCtrl
    UI -->|"GET/POST endpoints"| ClientCtrl
    UI -->|"Resource API"| ResourceCtrl
    UI -->|"Task API"| TaskCtrl

    MapComp <-->|"Google Maps API"| GMAP["Google Maps API"]:::external

    ClientRepo -->|"CRUD"| DB["MySQL/PostgreSQL"]:::database
    ShelterRepo -->|"CRUD"| DB
    TaskRepo -->|"CRUD"| DB

    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E2F0D9,stroke:#2E7D32,color:#2E7D32
    classDef controller fill:#C8E6C9,stroke:#388E3C,color:#388E3C
    classDef service fill:#DCEDC8,stroke:#689F38,color:#689F38
    classDef repo fill:#F1F8E9,stroke:#33691E,color:#33691E
    classDef mapper fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef model fill:#FFECB3,stroke:#FFB300,color:#E65100
    classDef config fill:#E3F2FD,stroke:#1976D2,color:#0D47A1
    classDef database fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#6A1B9A
    classDef users fill:#F5F5F5,stroke:#9E9E9E,color:#424242

    click UI "https://github.com/vatsalgandhi83/sj-hopes/tree/master/frontend/src/app"
    click APIWrappers "https://github.com/vatsalgandhi83/sj-hopes/tree/master/frontend/src/api"
    click Components "https://github.com/vatsalgandhi83/sj-hopes/tree/master/frontend/src/app/components"
    click AuthHook "https://github.com/vatsalgandhi83/sj-hopes/blob/master/frontend/src/app/hooks/useAuth.ts"
    click MapComp "https://github.com/vatsalgandhi83/sj-hopes/blob/master/frontend/src/app/components/ShelterMap.tsx"
    click Styles "https://github.com/vatsalgandhi83/sj-hopes/blob/master/frontend/src/app/globals.css"
    click Styles "https://github.com/vatsalgandhi83/sj-hopes/blob/master/frontend/next.config.js"
    click Styles "https://github.com/vatsalgandhi83/sj-hopes/blob/master/frontend/tsconfig.json"

    click MainApp "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/SjHopesApplication.java"
    click AdminCtrl "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/controller/AdminController.java"
    click ClientCtrl "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/controller/ClientController.java"
    click ResourceCtrl "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/controller/ResourceController.java"
    click TaskCtrl "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/controller/TaskController.java"
    click AnalyticsSvc "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/service/AnalyticsServiceImpl.java"
    click ClientSvc "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/service/ClientServiceImpl.java"
    click ResourceSvc "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/service/ResourceServiceImpl.java"
    click TaskSvc "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/service/TaskServiceImpl.java"
    click ClientRepo "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/repository/ClientRepository.java"
    click ShelterRepo "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/repository/ShelterRepository.java"
    click TaskRepo "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/repository/TaskRepository.java"
    click ClientMapper "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/mapper/ClientMapper.java"
    click ShelterMapper "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/mapper/ShelterMapper.java"
    click TaskMapper "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/java/com/sjhacks/sjhopes/mapper/TaskMapper.java"
    click Config "https://github.com/vatsalgandhi83/sj-hopes/blob/master/backend/sjHopes/src/main/resources/application.properties"
```
