# apexon-innovations/compass architecture

> Architecture diagram of the GitHub repository apexon-innovations/compass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apexon-innovations/compass
- Repository: https://github.com/apexon-innovations/compass

## Overview

1. **Overall shape**
   Compass is a monorepo organized around a data pipeline plus serving layer: external tool APIs feed **collectors**, raw data is transformed by **post processors**, stored in databases/data stores, and then exposed through **microservices** to the **React microfrontend**.

2. **Main architectural layers**
   The codebase splits into four top-level functional areas:
   - `collectors`: tool-specific ingestion services
   - `postprocessors`: batch transformation services
   - `microservices`: API layer and shared backend services
   - `microfrontend`: multiple React applications plus shared UI components

3. **Data ingestion boundary**
   Collectors are separate Spring Boot/Maven modules for tools like **Bitbucket**, **GitHub**, **Jira**, and **Sonar**. They call external SaaS/server APIs, normalize the responses, and push data into a raw storage layer referred to in the README as a **data lake**. Each collector has its own task classes, API clients, repository/config classes, and test fixtures.

4. **Transformation and canonical model**
   The `postprocessors` directory contains Python handlers for Bitbucket, GitHub, Jira, and Sonar. Their role is to read raw collected data, compute aggregations, and produce a **Unified Data Model (UDM)**. This is the key boundary between ingestion and serving: collectors capture source-shaped data, post processors reshape it for downstream consumption.

5. **Serving backends**
   The `microservices` directory is the runtime API layer. It contains multiple domain services:
   - **api-gateway**: front door and routing layer
   - **client-service**: client dashboard analytics and aggregations
   - **psr-service**: project/sprint/Jira-centric reporting
   - **strategy-service**: SCM/quality/security/strategic metrics
   - **onboard-service**: project onboarding and configuration management
   - **user-service**: authentication/authorization and identity
   - **commons**: shared backend libraries

6. **Backend data access pattern**
   The services are organized in a common Spring layering style: controllers → services → DAO/repository → persisted entities/aggregation objects. The backend modules rely heavily on the shared `commons/entities` package, which holds the canonical Mongo-style domain objects and aggregation VOs used across services.

7. **Shared backend infrastructure**
   The `microservices/commons` subtree is important architecturally because it centralizes reusable concerns:
   - `entities`: shared domain/document models and aggregation views
   - `utils`: constants and helper functions used across services
   - `security`: JWT/OAuth-related security configuration
   - `exception-handlers`: consistent API error handling
   - `file-upload`: S3 upload/download abstractions
   This keeps the business services thinner and aligns them on a shared data contract.

8. **Authentication and security path**
   User authentication is handled by `user-service`, which includes OAuth2/JWKS/security configuration. Other services reuse shared security utilities and JWT-related properties. The architecture suggests a token-based model where the user service issues/validates identity and other APIs trust that token chain.

9. **API gateway role**
   The `api-gateway` is a separate Spring Boot service and likely serves as the entry point for external clients. In architecture terms it sits in front of the domain services and centralizes routing and cross-cutting concerns rather than holding business logic.

10. **Frontend composition**
   `microfrontend` is not a single SPA; it contains multiple independently run React apps:
   - `login`
   - `client`
   - `pmo`
   - `reusable-components`
   - `server` to orchestrate local development
   The UI layer is modularized by audience/domain, with dashboards and drill-down screens aligned to the backend service domains.

11. **Frontend/backend contract**
   The microfrontends consume the API layer through service endpoints exposed by the microservices. The `reusable-components` package is a shared UI library used by the app shells and dashboard screens, which reduces duplication across the separate React applications.

12. **Domain alignment**
   The backend service boundaries match the front-end product areas:
   - PMO / strategic views map to `psr-service` and `strategy-service`
   - client dashboards map to `client-service`
   - onboarding flows map to `onboard-service`
   - login/authentication map to `user-service`
   This is useful for diagramming because each user-facing area corresponds to a backend domain service.

13. **Build and delivery**
   The repo is Maven-based for Java modules, npm-based for React apps, and includes Dockerfiles for several microservices. There is also a GitHub Actions Maven workflow. This indicates independent build units with containerized deployment as a supported runtime path.

14. **Key end-to-end flow**
   The main system flow is:
   external SCM/Jira/Sonar/Bitbucket data → collectors → raw lake → post processors/aggregations → persistent backend stores → microservices and gateway → React microfrontends.  
   Any architecture diagram should center this pipeline, with shared commons/security/components shown as cross-cutting dependencies rather than as separate business domains.

Main entry points: [`microservices/api-gateway`](https://github.com/apexon-innovations/compass/tree/main/microservices/api-gateway) (API gateway), [`microservices/commons`](https://github.com/apexon-innovations/compass/tree/main/microservices/commons) (Commons libs), [`collectors/core`](https://github.com/apexon-innovations/compass/tree/main/collectors/core) (Collector core), [`microfrontend/server`](https://github.com/apexon-innovations/compass/tree/main/microfrontend/server) (Dev server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_collectors["Collectors"]
  node_collector_core["Collector core<br/>shared ingestion core"]
  node_bitbucket_collector["Bitbucket<br/>collector service"]
  node_github_collector["GitHub<br/>collector service"]
  node_jira_collector["Jira<br/>collector service"]
  node_sonar_collector["Sonar<br/>collector service"]
end

subgraph group_group_postprocessors["Post processors"]
  node_udm_processors["UDM processors<br/>python batch layer"]
end

subgraph group_group_microservices["Microservices"]
  node_api_gateway["API gateway<br/>gateway service"]
  node_client_service["Client service<br/>dashboard API"]
  node_psr_service["PSR service<br/>reporting API"]
  node_strategy_service["Strategy service<br/>metrics API"]
  node_onboard_service["Onboard service<br/>config API"]
  node_user_service["User service<br/>identity API"]
end

subgraph group_group_frontend["Microfrontend"]
  node_react_login["Login app<br/>React app"]
  node_react_client["Client app<br/>React app"]
  node_react_pmo["PMO app<br/>React app"]
  node_ui_components["UI library<br/>shared React library"]
  node_frontend_orchestrator["Dev server<br/>frontend orchestrator"]
end

subgraph group_group_shared["Shared"]
  node_raw_lake[("Raw lake<br/>raw storage")]
  node_collector_store[("Backend stores<br/>persistent stores")]
  node_commons_libs["Commons libs<br/>shared backend libs"]
end

node_external_tools(("External tools<br/>source systems"))

node_external_tools -->|"SCM data"| node_bitbucket_collector
node_external_tools -->|"SCM data"| node_github_collector
node_external_tools -->|"issue data"| node_jira_collector
node_external_tools -->|"quality data"| node_sonar_collector
node_collector_core -.->|"runtime"| node_bitbucket_collector
node_collector_core -.->|"runtime"| node_github_collector
node_collector_core -.->|"runtime"| node_jira_collector
node_collector_core -.->|"runtime"| node_sonar_collector
node_bitbucket_collector -->|"write raw"| node_raw_lake
node_github_collector -->|"write raw"| node_raw_lake
node_jira_collector -->|"write raw"| node_raw_lake
node_sonar_collector -->|"write raw"| node_raw_lake
node_raw_lake -->|"read raw"| node_udm_processors
node_udm_processors -->|"write UDM"| node_collector_store
node_commons_libs -.->|"shared contract"| node_collector_store
node_collector_store -->|"serve via"| node_api_gateway
node_api_gateway -->|"route to"| node_client_service
node_api_gateway -->|"route to"| node_psr_service
node_api_gateway -->|"route to"| node_strategy_service
node_api_gateway -->|"route to"| node_onboard_service
node_api_gateway -->|"route to"| node_user_service
node_commons_libs -.->|"shared libs"| node_client_service
node_commons_libs -.->|"shared libs"| node_psr_service
node_commons_libs -.->|"shared libs"| node_strategy_service
node_commons_libs -.->|"shared libs"| node_onboard_service
node_commons_libs -.->|"shared libs"| node_user_service
node_user_service -->|"auth"| node_react_login
node_api_gateway -->|"api access"| node_react_client
node_api_gateway -->|"api access"| node_react_pmo
node_ui_components -.->|"shared UI"| node_react_client
node_ui_components -.->|"shared UI"| node_react_pmo
node_frontend_orchestrator -.->|"dev run"| node_react_login
node_frontend_orchestrator -.->|"dev run"| node_react_client
node_frontend_orchestrator -.->|"dev run"| node_react_pmo
node_frontend_orchestrator -.->|"dev run"| node_ui_components

click node_collector_core "https://github.com/apexon-innovations/compass/tree/main/collectors/core"
click node_bitbucket_collector "https://github.com/apexon-innovations/compass/tree/main/collectors/bitbucket-collector"
click node_github_collector "https://github.com/apexon-innovations/compass/tree/main/collectors/github-collector"
click node_jira_collector "https://github.com/apexon-innovations/compass/tree/main/collectors/jira-collector"
click node_sonar_collector "https://github.com/apexon-innovations/compass/tree/main/collectors/sonar-collector"
click node_udm_processors "https://github.com/apexon-innovations/compass/tree/main/postprocessors"
click node_collector_store "https://github.com/apexon-innovations/compass/tree/main/microservices/commons/entities"
click node_api_gateway "https://github.com/apexon-innovations/compass/tree/main/microservices/api-gateway"
click node_client_service "https://github.com/apexon-innovations/compass/tree/main/microservices/client-service"
click node_psr_service "https://github.com/apexon-innovations/compass/tree/main/microservices/psr-service"
click node_strategy_service "https://github.com/apexon-innovations/compass/tree/main/microservices/strategy-service"
click node_onboard_service "https://github.com/apexon-innovations/compass/tree/main/microservices/onboard-service"
click node_user_service "https://github.com/apexon-innovations/compass/tree/main/microservices/user-service"
click node_commons_libs "https://github.com/apexon-innovations/compass/tree/main/microservices/commons"
click node_react_login "https://github.com/apexon-innovations/compass/tree/main/microfrontend/login"
click node_react_client "https://github.com/apexon-innovations/compass/tree/main/microfrontend/client"
click node_react_pmo "https://github.com/apexon-innovations/compass/tree/main/microfrontend/pmo"
click node_ui_components "https://github.com/apexon-innovations/compass/tree/main/microfrontend/reusable-components"
click node_frontend_orchestrator "https://github.com/apexon-innovations/compass/tree/main/microfrontend/server"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector_core,node_bitbucket_collector,node_github_collector,node_jira_collector,node_sonar_collector toneBlue
class node_udm_processors toneAmber
class node_api_gateway,node_client_service,node_psr_service,node_strategy_service,node_onboard_service,node_user_service toneMint
class node_react_login,node_react_client,node_react_pmo,node_ui_components,node_frontend_orchestrator toneRose
class node_raw_lake,node_collector_store,node_commons_libs toneIndigo
class node_external_tools toneNeutral
```

## Components

### Collectors

Source-specific ingestion services

- [Collector core](https://github.com/apexon-innovations/compass/tree/main/collectors/core): shared ingestion core · Common collector runtime, auth, client, event, model, and persistence infrastructure · `collectors/core`
- [Bitbucket](https://github.com/apexon-innovations/compass/tree/main/collectors/bitbucket-collector): collector service · Spring Boot ingestion module for Bitbucket SCM data · `collectors/bitbucket-collector`
- [GitHub](https://github.com/apexon-innovations/compass/tree/main/collectors/github-collector): collector service · Spring Boot ingestion module for GitHub SCM data · `collectors/github-collector`
- [Jira](https://github.com/apexon-innovations/compass/tree/main/collectors/jira-collector): collector service · Spring Boot ingestion module for Jira feature and sprint data · `collectors/jira-collector`
- [Sonar](https://github.com/apexon-innovations/compass/tree/main/collectors/sonar-collector): collector service · Spring Boot ingestion module for Sonar quality data · `collectors/sonar-collector`

### Post processors

Batch transformation to UDM

- [UDM processors](https://github.com/apexon-innovations/compass/tree/main/postprocessors): python batch layer · Python handlers that reshape raw data into the Unified Data Model · `postprocessors`

### Microservices

API and backend services

- [API gateway](https://github.com/apexon-innovations/compass/tree/main/microservices/api-gateway): gateway service · Front door for routing and cross-cutting concerns · `microservices/api-gateway`
- [Client service](https://github.com/apexon-innovations/compass/tree/main/microservices/client-service): dashboard API · Client-facing analytics, health, and dashboard aggregations · `microservices/client-service`
- [PSR service](https://github.com/apexon-innovations/compass/tree/main/microservices/psr-service): reporting API · Project, sprint, Jira, operational, and business reporting APIs · `microservices/psr-service`
- [Strategy service](https://github.com/apexon-innovations/compass/tree/main/microservices/strategy-service): metrics API · SCM, quality, security, and strategic metrics APIs · `microservices/strategy-service`
- [Onboard service](https://github.com/apexon-innovations/compass/tree/main/microservices/onboard-service): config API · Project onboarding and configuration management APIs · `microservices/onboard-service`
- [User service](https://github.com/apexon-innovations/compass/tree/main/microservices/user-service): identity API · OAuth2, JWKS, authorization, and user identity service · `microservices/user-service`

### Microfrontend

React apps and shared UI

- [Login app](https://github.com/apexon-innovations/compass/tree/main/microfrontend/login): React app · Authentication and landing experience · `microfrontend/login`
- [Client app](https://github.com/apexon-innovations/compass/tree/main/microfrontend/client): React app · Client dashboard microfrontend · `microfrontend/client`
- [PMO app](https://github.com/apexon-innovations/compass/tree/main/microfrontend/pmo): React app · PMO and strategic microfrontend · `microfrontend/pmo`
- [UI library](https://github.com/apexon-innovations/compass/tree/main/microfrontend/reusable-components): shared React library · Reusable React components, widgets, and visual building blocks · `microfrontend/reusable-components`
- [Dev server](https://github.com/apexon-innovations/compass/tree/main/microfrontend/server): frontend orchestrator · Local development launcher for the modular frontend apps · `microfrontend/server`

### Shared

Cross-cutting libraries and storage

- **Raw lake**: raw storage · Landing zone for source-shaped collected data
- [Backend stores](https://github.com/apexon-innovations/compass/tree/main/microservices/commons/entities): persistent stores · Shared Mongo-style documents and service-owned collections used by APIs · `microservices/commons/entities`
- [Commons libs](https://github.com/apexon-innovations/compass/tree/main/microservices/commons): shared backend libs · Reusable entities, security, exceptions, file upload, and utility packages · `microservices/commons`

### Other components

- **External tools**: source systems · Bitbucket, GitHub, Jira, and Sonar APIs that provide raw operational data

## Connections

- External tools → Bitbucket: SCM data · Bitbucket API ingestion
- External tools → GitHub: SCM data · GitHub API ingestion
- External tools → Jira: issue data · Jira API ingestion
- External tools → Sonar: quality data · Sonar API ingestion
- Collector core → Bitbucket: runtime · Shared collector framework and data models
- Collector core → GitHub: runtime · Shared collector framework and data models
- Collector core → Jira: runtime · Shared collector framework and data models
- Collector core → Sonar: runtime · Shared collector framework and data models
- Bitbucket → Raw lake: write raw · Persist collected Bitbucket payloads
- GitHub → Raw lake: write raw · Persist collected GitHub payloads
- Jira → Raw lake: write raw · Persist collected Jira payloads
- Sonar → Raw lake: write raw · Persist collected Sonar payloads
- Raw lake → UDM processors: read raw · Batch transform raw source-shaped data
- UDM processors → Backend stores: write UDM · Produce canonical domain and aggregation data
- Commons libs → Backend stores: shared contract · Canonical entities and aggregation value objects
- Backend stores → API gateway: serve via · Backend data exposed through the API front door
- API gateway → Client service: route to · Client dashboard endpoints
- API gateway → PSR service: route to · Project and sprint reporting endpoints
- API gateway → Strategy service: route to · Strategic and quality metrics endpoints
- API gateway → Onboard service: route to · Onboarding and configuration endpoints
- API gateway → User service: route to · Authentication and identity endpoints
- Commons libs → Client service: shared libs · Shared entities, utils, and security
- Commons libs → PSR service: shared libs · Shared entities, utils, and security
- Commons libs → Strategy service: shared libs · Shared entities, utils, and security
- Commons libs → Onboard service: shared libs · Shared entities, utils, and security
- Commons libs → User service: shared libs · Shared entities, utils, and security
- User service → Login app: auth · Login and token-based identity flow
- API gateway → Client app: api access · Frontend consumes backend APIs through the gateway
- API gateway → PMO app: api access · Frontend consumes backend APIs through the gateway
- UI library → Client app: shared UI · Reusable dashboard components
- UI library → PMO app: shared UI · Reusable dashboard components
- Dev server → Login app: dev run · Local development launcher
- Dev server → Client app: dev run · Local development launcher
- Dev server → PMO app: dev run · Local development launcher
- Dev server → UI library: dev run · Shared UI library development