# kenya-jug/regression architecture

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

- Interactive diagram: https://gitdiagram.com/kenya-jug/regression
- Repository: https://github.com/kenya-jug/regression

## Overview

##### Project type and purpose
- This is a Spring Boot–based backend service (“Regression”) whose sole responsibility is to collect, store, and analyze application error logs via REST APIs.
- It targets high-volume log ingestion, fast retrieval, AI-powered analysis, and exposes metrics for monitoring.

##### File structure
- Top-level:
- pom.xml (build & dependencies)
- src/main/java/com/kenyajug/regression – contains the application entrypoint (RegressionApplication), servlet initializer, domain entities, repositories, and utility classes.
- src/main/resources – application.properties, DB changelog scripts, SQL schema.
- specification/ – design docs for API and persistence.
- src/test – unit and integration tests.
- .github/workflows/maven.yml – CI pipeline.

##### README for additional insights
- RESTful API for log ingestion and retrieval
- AI-driven modules for anomaly detection and root-cause analysis
- JWT/OAuth2 security
- Metrics endpoint (/metrics) for monitoring
- Persist to relational or NoSQL database, migrations via changelog

a. Main components
1) External Clients
- Log Producers (microservices, apps sending JSON via HTTP POST)
- API Consumers (dashboards, CLI, or other services fetching logs via GET)
- Swagger UI / OpenAPI client
2) API & Security Layer
- Spring MVC Controllers (LogIngestionController, LogRetrievalController, AnalysisController)
- Security filters (JWT/OAuth2 filter chain)
3) Business Logic Layer
- Services:
- IngestionService (validates, transforms, hands off to persistence)
- RetrievalService (applies filters, pagination)
- AIAnalysisService (calls embedded or external ML models)
4) Persistence Layer
- Repositories implementing CrudRepository
- Domain Entities: AppLog, Application, LogsMetadata, User
- Database Migration (Liquibase/Flyway changelog scripts)
- Database (SQLite/PostgreSQL)
5) Monitoring & Metrics
- Spring Actuator endpoints (/metrics, /health)
- Exporters (Prometheus endpoint)
6) Infrastructure & CI/CD
- Docker container
- GitHub Actions (maven build, test, coverage)
- Container registry & orchestration (optional Kubernetes)

b. Relationships & interactions
- Clients → HTTP POST/GET → Controllers
- Controllers → (via Security Filter) → Services
- Services → Repositories → Database
- Services → AIAnalysis component / external ML service
- Actuator module intercepts and exposes metrics to Monitoring system
- CI pipeline triggers Maven build, runs tests, builds Docker image, pushes to registry

c. Architectural patterns & principles
- Layered architecture (Controller → Service → Repository → DB)
- Domain-driven design (clear Entities and Repositories)
- Repository pattern for data access
- Separation of concerns (ingestion vs retrieval vs analysis)
- Pluggable AI model architecture (swap or extend analysis module)
- Database migrations for schema evolution

d. Key technologies & frameworks
- Spring Boot, Spring MVC, Spring Data JPA
- SQLite / PostgreSQL (configurable via application.properties)
- Liquibase/Flyway for changelogs
- JWT/OAuth2 (Spring Security)
- Spring Actuator for metrics
- Maven, GitHub Actions
- Docker

##### Detailed breakdown of components
- API Tier:
[API Layer – Spring MVC Controllers] – secured by [Security Filter Chain]
- Service Tier:
[IngestionService] ↔ [Repository Layer]
[RetrievalService] ↔ [Repository Layer]
[AIAnalysisService] ↔ [ML Model / External AI Service]
- Data Tier:
[Repositories] → [Database (with migrations)]
- Monitoring:
[Actuator] → [Prometheus / Grafana]
- Infrastructure:
[GitHub Repo] → [GitHub Actions] → [Docker Image] → [K8s Cluster / Docker Host]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        ExternalApps["External Apps<br/>(POST /logs)"]:::external
        AdminUI["Admin UI<br/>(GET /logs)"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    %% API & Security Layer
    subgraph "API & Security Layer"
        SecurityFilter["Security Filter Chain<br/>(JWT/OAuth2)"]:::api
        LogIngestCtrl["LogIngestionController"]:::api
        LogRetrievalCtrl["LogRetrievalController"]:::api
        AnalysisCtrl["AnalysisController"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        IngestionService["IngestionService"]:::business
        RetrievalService["RetrievalService"]:::business
        AIAnalysisService["AIAnalysisService"]:::business
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        subgraph Repositories
            AppLogRepo["AppLogRepository"]:::data
            AppsRepo["ApplicationsRepository"]:::data
            LogsMetaRepo["LogsMetadataRepository"]:::data
            UserRepo["UserRepository"]:::data
        end
        subgraph Entities
            AppLogEnt["AppLog"]:::data
            ApplicationEnt["Application"]:::data
            LogsMetaEnt["LogsMetadata"]:::data
            UserEnt["User"]:::data
        end
        DBMigration["DB Migrations<br/>(Liquibase/Flyway)"]:::data
        Database["Database<br/>(SQLite/PostgreSQL)"]:::data
    end

    %% Monitoring & Metrics
    subgraph "Monitoring & Metrics"
        Actuator["Spring Actuator<br/>(/metrics,/health)"]:::external
        Prometheus["Prometheus Endpoint"]:::external
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        GitHubRepo["GitHub Repo"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        DockerImage["Docker Image"]:::infra
        Deploy["K8s/Docker Host"]:::infra
    end

    %% Connections
    ExternalApps -->|POST /logs| LogIngestCtrl
    AdminUI -->|GET /logs| LogRetrievalCtrl
    SwaggerUI -->|OpenAPI| AnalysisCtrl

    LogIngestCtrl --> SecurityFilter
    LogRetrievalCtrl --> SecurityFilter
    AnalysisCtrl --> SecurityFilter

    SecurityFilter --> IngestionService
    SecurityFilter --> RetrievalService
    SecurityFilter --> AIAnalysisService

    IngestionService -->|uses| AppLogRepo
    IngestionService -->|uses| AppsRepo
    RetrievalService -->|uses| LogsMetaRepo
    AIAnalysisService -->|uses| UserRepo

    AppLogRepo --> AppLogEnt
    AppsRepo --> ApplicationEnt
    LogsMetaRepo --> LogsMetaEnt
    UserRepo --> UserEnt

    AppLogRepo --> Database
    AppsRepo --> Database
    LogsMetaRepo --> Database
    UserRepo --> Database

    DBMigration --> Database

    Actuator --> Prometheus

    GitHubRepo --> GitHubActions --> DockerImage --> Deploy

    %% Click Events
    click AppLogRepo "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/repository/AppLogRepository.java"
    click AppsRepo "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/repository/ApplicationsRepository.java"
    click LogsMetaRepo "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/repository/LogsMetadataRepository.java"
    click UserRepo "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/repository/UserRepository.java"
    click AppLogEnt "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/entities/AppLog.java"
    click ApplicationEnt "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/entities/Application.java"
    click LogsMetaEnt "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/entities/LogsMetadata.java"
    click UserEnt "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/entities/User.java"
    click SecurityFilter "https://github.com/kenya-jug/regression/blob/main/src/main/java/com/kenyajug/regression/ServletInitializer.java"
    click GitHubActions "https://github.com/kenya-jug/regression/blob/main/.github/workflows/maven.yml"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef business fill:#D0FFD8,stroke:#000,stroke-width:1px
    classDef data fill:#FFE6B3,stroke:#000,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px
```
