Scala Log Analytics API

Log analytics REST API: ZIO HTTP server parsing Common Log Format (CLF) access logs with ZIO Streams, Scala 3, purely functional effects.

---

Architecture Overview

flowchart TD
    subgraph HTTP["HTTP ROUTES"]
        style HTTP fill:#dbeafe,stroke:#3b82f6
        R["AnalyticsService\n(9 GET routes)"]
    end
    subgraph STREAM["STREAM PIPELINE"]
        style STREAM fill:#dcfce7,stroke:#22c55e
        FILE["clf-logs/formatted_logs.txt"]
        S["ZStream[CommonLog]"]
    end
    subgraph DOMAIN["DOMAIN"]
        style DOMAIN fill:#fef9c3,stroke:#eab308
        CL["CommonLog (CLF parser)"]
        LT["LogTypes (opaque types)"]
        HR["HttpRequest / HttpStatus / HttpVersion"]
    end
    Client -->|"GET /..."| R
    R --> S
    FILE -->|"lines"| S
    S -->|"parse"| CL
    CL --> LT
    CL --> HR

Loading

Each incoming HTTP request triggers ZStream to read and parse the log file. CommonLog.apply validates each line against the CLF regex, constructing typed domain values via opaque types. Aggregation happens in-memory per request using standard Scala collection operations.

Layer Overview

Layer	Package	Responsibilities
HTTP Routes	api/apps/	Route matching with Http.collectZIO, stream aggregation per endpoint, JSON response via zio-json
Domain	domain/	CLF line parsing, opaque type construction with Either-based validation, HTTP enums (HttpMethod, HttpStatus, HttpVersion), Monoid[Bytes] via Cats

---

Architecture Decisions

ZIO as a unified effect and streaming stack

Context. Building a streaming HTTP API requires choices across effect system, stream processing, HTTP server, and JSON serialization. Mixing libraries (Akka Streams + http4s + Circe) means different effect types at each boundary.

Decision. Use ZIO as the single dependency: zio, zio-streams, zio-http, and zio-json all share the ZIO[R, E, A] type.

Consequence. Error handling, resource management, and composition are consistent across all layers with a single runtime. No Future/IO/Task conversions at layer boundaries.

---

Getting Started

Prerequisites: JDK 21+, sbt 1.9.8

git clone https://github.com/<handle>/ScalaLogAnalyticsAPI.git
cd ScalaLogAnalyticsAPI
sbt run

Server starts at http://localhost:8080.

Log generation requires synth CLI and Python 3 in PATH. The API reads from clf-logs/formatted_logs.txt — populate it before querying endpoints.

---

Tech Stack

Concern	Technology
Language	Scala 3.3.1
HTTP server	ZIO HTTP 3.0.0-RC2
Streaming	ZIO Streams 2.0.13
JSON	ZIO JSON 0.5.0
Functional abstractions	Cats Core 2.9.0 (Monoid)
Build	sbt 1.9.8
Testing	MUnit 0.7.29

---

Testing

25 tests covering CLF line parsing, HTTP request parsing, and opaque type validation.

sbt test                                    # all tests
sbt "testOnly domain.http.TestCommonLog"    # single suite

---

API Reference

Full endpoint list with request/response examples: API_REFERENCE.md.