apexon-innovations/compass

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.