# dragand-ukr/jobspotter architecture

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

- Interactive diagram: https://gitdiagram.com/dragand-ukr/jobspotter
- Repository: https://github.com/dragand-ukr/jobspotter

## Overview

##### Main Components
- Backend Microservices: There are several Spring Boot microservices under the “jobspotter_backend/services” directory:
- Config Server – centralizes configuration (found in services/config-server).
- Discovery Service – handles service registration and discovery (services/discovery).
- Gateway Service – the API gateway that intercepts requests, handles authentication (see security filters and token rotation), and routes them to the appropriate services (services/gateway).
- Job Post Service – manages job postings, search (with full-text search using Lucene/Hibernate Search), and address-related functionality.
- Notification Service – pushes real-time notifications using Kafka and SSE.
- Report Service – handles administrative report management backed by MongoDB.
- Review Service – manages reviews and ratings for job posts.
- User Service – deals with user management, authentication integration via Keycloak, caching, and file storage (AWS S3 integration).
- Frontend: Located in “jobspotter_frontend”, it likely is a React/Vite-based application. It interacts with the backend via the API Gateway.
- Databases and External Tools:
- PostgreSQL and MongoDB for database needs.
- Kafka for messaging.
- Keycloak for authentication/authorization.
- AWS S3 for file storage.
- (Optional) Redis caching (to be implemented).

##### How Components Interact
- User requests originate from the frontend and are routed via the API Gateway.
- The Gateway performs initial token extraction (HTTP-only cookies) and authorization by interfacing with Keycloak.
- Validated requests are forwarded to the appropriate microservice (job-post, user, review, etc.).
- All microservices obtain their configuration from the Config Server and register with the Discovery Service for dynamic lookup.
- The Notification Service uses Kafka to publish events; these events are consumed by clients (e.g., via SSE in the frontend).
- For reporting, the Report Service leverages MongoDB’s flexible schema while other data storage (like job posts, users) is likely stored in PostgreSQL.
- Some inter-service communication is visible in client modules (e.g., job-post calling review or user service APIs).

##### Architectural Patterns and Design Principles
- Microservices Architecture: Each responsibility is split among loosely coupled services.
- API Gateway: Acts as the “face” of the backend, handling cross-cutting concerns (authentication and token refresh).
- Service Discovery: Ensures responsiveness and load balancing among services.
- Centralized Configuration: Provided through the Config Server for consistency.
- Real-Time Messaging: Kafka integration for notifications.
- Secure Authentication: Managed via Keycloak with token-based authorization.
- Containerization & Scalability: Docker (as indicated by docker-compose files) and planned GitHub Action CI/CD processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    UB("User Browser"):::user
    FE("Frontend Application\n(React/Vite)"):::frontend
    UB -->|"initiates request"| FE
    FE -->|"calls"| GW("API Gateway\n(Request Routing & Authentication)"):::microservice

    %% Backend Microservices
    GW -->|"routes to"| JP("Job Post Service\n(Manage job postings & search)"):::microservice
    GW -->|"routes to"| NS("Notification Service\n(Real-time notifications)"):::microservice
    GW -->|"routes to"| RS("Report Service\n(Admin reporting)"):::microservice
    GW -->|"routes to"| RV("Review Service\n(Reviews & ratings)"):::microservice
    GW -->|"routes to"| US("User Service\n(User management & auth integration)"):::microservice

    %% Inter-service Communications
    JP <-->|"interacts"| RV
    JP <-->|"interacts"| US

    %% External Infrastructure
    GW -->|"auth-check"| KC("Keycloak\n(Authentication)"):::infra
    NS -->|"publish-events"| KF("Kafka\n(Messaging)"):::infra
    NS -->|"SSE-notify"| FE
    RS -->|"data storage"| MG("MongoDB"):::infra
    JP -->|"data storage"| PG("PostgreSQL"):::infra
    US -->|"data storage"| PG
    RV -->|"data storage"| PG
    US -->|"file storage"| S3("AWS S3"):::infra
    US -->|"caching"| RD("Redis"):::infra

    %% Configuration and Service Discovery for Microservices
    GW ---|"gets config"| CS("Config Server"):::infra
    GW ---|"registers"| DS("Discovery Service"):::infra
    JP ---|"gets config"| CS
    JP ---|"registers"| DS
    NS ---|"gets config"| CS
    NS ---|"registers"| DS
    RS ---|"gets config"| CS
    RS ---|"registers"| DS
    RV ---|"gets config"| CS
    RV ---|"registers"| DS
    US ---|"gets config"| CS
    US ---|"registers"| DS

    %% Subgraph: Infrastructure Components (grouped for clarity)
    subgraph "Infrastructure Components"
        CS
        DS
        KC
        KF
        MG
        PG
        S3
        RD
    end

    %% Click Events
    click CS "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/config-server"
    click DS "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/discovery"
    click GW "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/gateway"
    click JP "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/job-post"
    click NS "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/notification"
    click RS "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/report"
    click RV "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/review"
    click US "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_backend/services/user"
    click FE "https://github.com/dragand-ukr/jobspotter/tree/main/jobspotter_frontend"

    %% Styles
    classDef user fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef frontend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef microservice fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef infra fill:#d4edda,stroke:#28a745,stroke-width:2px;
```
