Architecture Overview

ServiceHop is a multi-module system for API call insight and cacheability analysis.

System Components

┌─────────────────┐     ┌─────────────────┐
│  servicehop-cli │     │  servicehop-web │
│   (Data Ingest) │     │    (Insights)   │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │   servicehop-core     │
         │    (API & Engine)     │
         └───────────┬───────────┘
                     │
                     ▼
              ┌─────────────┐
              │ PostgreSQL  │
              └─────────────┘

Component	Purpose
servicehop-cli	Command-line interface for data ingestion and operations
servicehop-web	Web application for insight visualization and administration
servicehop-core	Backend API service with insight engine
PostgreSQL	Data storage with partitioned tables

Technology Stack

Layer	Technology
Runtime	Java 21
Backend	Spring Boot 3.x
Database	PostgreSQL 15+
CLI	JLine 3
Web UI	Thymeleaf + Bootstrap
AI	Spring AI with OpenAI

Data Flow

1. Ingestion

CLI → Core API → Call Storage (partitioned by day)
                        ↓
                 Service Registry (auto-created)

The CLI sends call records to the Core API. Calls are stored in date-partitioned tables. Services are automatically registered when their first call is ingested.

2. Aggregation

Scheduler → Aggregation Jobs → Hourly Rollups
                             → Daily Rollups

Background jobs compute pre-aggregated statistics for efficient querying.

3. Insight Generation

Orchestrator → Check Data Changes → Execute Calculators
                                           ↓
                                    Store Insights

The orchestrator monitors data changes and triggers insight calculations when new data is available or existing insights become stale.

4. Retrieval

CLI/Web → Core API → Read Insights
                   → Read Statistics
                   → Read Call Samples

Insights and data are retrieved via the Core API, consumed by both CLI and Web.

Module Relationships

graph TD
    CLI[servicehop-cli] --> API[servicehop-api]
    WEB[servicehop-web] --> API
    CORE[servicehop-core] --> API
    CLI --> |REST| CORE
    WEB --> |REST| CORE
    CORE --> DB[(PostgreSQL)]

servicehop-api is a shared library containing DTOs, API client, and validation annotations used by all other modules.