How middlewarehq/middleware works
High-Level Architecture Components
The system consists of three main services:
• Web Server (Frontend - Next.js)
• Analytics Server (Backend API)
• Sync Server (Background Processing)
• Supporting Infrastructure (PostgreSQL and Redis)
Key Components
a) Frontend Layer:
• Next.js Web Application (port 3333)
• Client-side state management (Redux store)
• API integration layer
• Authentication system
b) Backend Services:
• Analytics Server (port 9696)
• API endpoints (/mhq/api/*)
• Service layer for metrics calculation
• Data processing modules
• Sync Server (port 9697)
• ETL processes for different providers
• Background job processing
• Data synchronization
c) Data Layer:
• PostgreSQL database
• Redis for caching/queue management
d) External Integrations:
• GitHub API
• GitLab API
• Incident Management Systems
[Client Layer]
• ↓ ↑
[API Gateway/Load Balancer]
• ↓ ↑
[Service Layer]
• ↓ ↑
[Data Layer]
• ↓ ↑
[External Services]
Important Flows to Highlight
a) Data Collection Flow:
• How the Sync Server pulls data from Git providers
• ETL pipeline for processing repository data
• Data storage flow into PostgreSQL
b) Analytics Flow:
• How DORA metrics are calculated
• Data aggregation paths
• Caching mechanisms
c) User Interaction Flow:
• Authentication process
• Team management
• Metrics visualization requests
Component Details
For each major component, include:
• Service name
• Port number (if applicable)
• Primary responsibilities
• Key dependencies
Interactions
• Data flows (thick lines)
Notes Section
A notes section explaining:
• Scaling considerations
• Security implementations
• Key architectural decisions
• Performance optimizations