# astrolin/ephemeris-api architecture

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

- Interactive diagram: https://gitdiagram.com/astrolin/ephemeris-api
- Repository: https://github.com/astrolin/ephemeris-api

## Overview

##### Main Components
a. Clients
- Web or mobile applications (HTTP consumers)
- Command-line tools or curl (for testing/demo)
b. API Service Container
- Pedestal HTTP server (Jetty or Immutant adapter)
- Static asset handler (serves resources/public)
c. Application Core
- Routing and endpoints (src/ephemeris_api/server.clj, views.clj)
- Service layer (src/ephemeris_api/service.clj)
- Core logic (src/ephemeris_api/core.clj)
- Configuration loader (nomad via src/ephemeris_api/config.clj + resources/config.edn + env vars)
d. Ephemeris Library
- Third-party ephemeris code (astrolet/ephemeris)
e. Logging & Monitoring
- logback.xml (structured logs to console or file)
f. Build & Deployment Pipeline
- Leiningen (project.clj, dev/dev.clj)
- Dockerfiles & Heroku Procfile (containerization & PaaS)
- CI configs (Travis CI: .travis.yml, CircleCI: circle.yml)

##### Relationships & Data Flow
- Clients → HTTP(S) request → Pedestal routing layer
- Pedestal → invokes service functions → passes request data
- Service layer → calls core logic → core logic → ephemeris library
- Ephemeris library → computes positions → returns data to core
- Core → service layer → converts result to JSON via views → response
- Static file requests → Pedestal’s resource interceptor → serves index.html/css
- Throughout: configuration parameters injected from nomad/environ → influence port, host, API base path
- Logs emitted at each request/response boundary, written by logback

##### Architectural Patterns & Principles
- Microservice: self-contained HTTP API for a single responsibility (functional transformation)
- Stateless, single-purpose service; no database dependency
- Functional core (pure logic) separated from I/O layer (Pedestal)
- Configuration as code via nomad + environment overrides
- Containerizable: environment-agnostic, deployable to Docker, Heroku, OpenShift, etc.

##### Technologies & Frameworks
- Clojure (runtime, REPL-driven dev)
- Pedestal (HTTP framework) with Jetty/Immutant adapters
- Leiningen (build + REPL + uberjar)
- Nomad/environ (configuration management)
- Docker/Heroku/OpenShift manifests for deployment
- logback for logging
- CI: Travis, CircleCI

##### Essential Elements
– Component names and roles (Server, Router, Service Layer, Core Logic, Ephemeris Library)
– Environment variables pointing into config loader
– Deployment targets (Docker container pushed to Heroku, etc.)
– CI triggers and build artifacts (uberjar, Docker image)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        Web["Web/Mobile Clients"]:::external
        CLI["CLI / curl"]:::external
    end

    %% API Service Container
    subgraph "API Service Container"
        direction TB
        Pedestal["Pedestal HTTP Server"]:::appcomponent
        Router["Routing & Endpoints"]:::appcomponent
        Service["Service Layer"]:::appcomponent
        Core["Core Logic"]:::appcomponent
        Library[(Ephemeris Library)]:::library
        StaticAssets["Static Assets"]:::document
        ConfigLoader["Configuration Loader"]:::appcomponent
        ConfigFile["Default Config (config.edn)"]:::infra
        DevConfig["Dev Config (dev/dev.clj)"]:::infra
        EnvVars["Environment Variables"]:::infra
        Logback["Logback Config"]:::infra
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHub["GitHub Repo"]:::cicd
        Travis["Travis CI"]:::cicd
        CircleCI["CircleCI"]:::cicd
        DockerRegistry["Docker Registry"]:::cicd
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        direction TB
        Docker["Docker Container"]:::infra
        Heroku["Heroku / OpenShift"]:::infra
    end

    %% Data flows
    Web -->|HTTP GET /positions| Pedestal
    CLI -->|HTTP GET /positions| Pedestal
    Pedestal -->|routes request| Router
    Router -->|invoke| Service
    Service -->|calls| Core
    Core -->|computes| Library
    Library -->|returns data| Core
    Core -->|result| Service
    Service -->|prepare JSON| Router
    Router -->|respond| Pedestal
    Pedestal -->|JSON response| Web
    Pedestal -->|serves| StaticAssets
    StaticAssets -->|static files| Web

    %% Configuration flow
    ConfigFile -.->|loads defaults| ConfigLoader
    DevConfig -.->|overrides| ConfigLoader
    EnvVars -.->|override| ConfigLoader
    ConfigLoader -->|injects settings| Pedestal

    %% Logging
    Pedestal -->|logs events| Logback
    Service -->|logs events| Logback

    %% CI/CD flow
    GitHub -->|push| Travis
    GitHub -->|push| CircleCI
    Travis -->|build image| DockerRegistry
    CircleCI -->|build image| DockerRegistry
    DockerRegistry -->|pull| Docker
    Docker -->|deploy| Heroku

    %% Click Events
    click Pedestal "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/server.clj"
    click StaticAssets "https://github.com/astrolin/ephemeris-api/tree/develop/resources/public"
    click Router "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/server.clj"
    click Router "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/views.clj"
    click Service "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/service.clj"
    click Core "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/core.clj"
    click ConfigLoader "https://github.com/astrolin/ephemeris-api/blob/develop/src/ephemeris_api/config.clj"
    click ConfigFile "https://github.com/astrolin/ephemeris-api/blob/develop/resources/config.edn"
    click DevConfig "https://github.com/astrolin/ephemeris-api/blob/develop/dev/dev.clj"
    click Logback "https://github.com/astrolin/ephemeris-api/blob/develop/resources/logback.xml"
    click project "https://github.com/astrolin/ephemeris-api/blob/develop/project.clj"
    click DevConfig "https://github.com/astrolin/ephemeris-api/blob/develop/dev/dev.clj"
    click Docker "https://github.com/astrolin/ephemeris-api/tree/develop/Dockerfile"
    click Docker "https://github.com/astrolin/ephemeris-api/blob/develop/Dockerfile.jetty"
    click Procfile "https://github.com/astrolin/ephemeris-api/tree/develop/Procfile"
    click Travis "https://github.com/astrolin/ephemeris-api/blob/develop/ .travis.yml"
    click CircleCI "https://github.com/astrolin/ephemeris-api/blob/develop/circle.yml"
    click StaticAssets "https://github.com/astrolin/ephemeris-api/blob/develop/resources/pages/index.html"
    click StaticAssets "https://github.com/astrolin/ephemeris-api/blob/develop/resources/public/css/main.css"
    click StaticAssets "https://github.com/astrolin/ephemeris-api/blob/develop/resources/styles/main.scss"

    %% Styles
    classDef appcomponent fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef library fill:#D5F5E3,stroke:#1e8449,color:#1e8449
    classDef infra fill:#FFE5B4,stroke:#cc7000,color:#cc7000
    classDef cicd fill:#E8E8E8,stroke:#888888,color:#444444
    classDef external fill:#FFFFFF,stroke:#444444,color:#444444
    classDef document fill:#F5F5F5,stroke:#AAAAAA,color:#555555,shape:rect
```
