EASE Platform Topology
Understanding the complete architecture and service interaction patterns
Overview
The EASE platform is built as a modular, microservices-based architecture designed for enterprise-scale multi-tenant applications. This document provides a comprehensive view of all services, their interactions, and deployment topology.
Current Stack Topology
Service Architecture Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ EASE Platform │
│ (Multi-Tenant Architecture) │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ Frontend Applications │
│ (Port 3000-3999) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ StackExplorer │ │ Bookings App │ │ Custom App │ │
│ │ Port 3000 │ │ Port 3001 │ │ Port 3002 │ │
│ │ │ │ │ │ │ │
│ │ • Documentation │ │ • Reference App │ │ • Your App │ │
│ │ • Interactive │ │ • Multi-tenant │ │ • EASE SDK │ │
│ │ • Self-learning │ │ • Full RBAC │ │ │ │
│ └────────┬─────────┘ └────────┬─────────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────────┼─────────────────────┘ │
│ │ │
└──────────────────────────────────┼──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Platform Services │
│ (Port 4000-4999) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ App Launcher (Port 4000) │ │
│ │ Central portal • Service discovery • App registry │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Observability Dashboard (Port 4001) │ │
│ │ Real-time monitoring • Event streaming • Analytics │ │
│ └───────────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Telemetry Service (Port 4002) [Planned] │ │
│ │ • Event collection • PostgreSQL storage │ │
│ │ • Multi-tenant isolation • WebSocket streaming │ │
│ │ • API key authentication • Time-series analytics │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Backend APIs │
│ (Port 5000-5999) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ StackExplorer API│ │ Bookings API │ │ Auth Service│ │
│ │ Port 5001 │ │ Port 5002 │ │ Port 5003 │ │
│ │ (.NET Core) │ │ (.NET Core) │ │ (.NET Core) │ │
│ │ │ │ │ │ │ │
│ │ • REST API │ │ • REST API │ │ • JWT Auth │ │
│ │ • Swagger │ │ • Multi-tenant │ │ • OAuth2 │ │
│ │ • Health checks │ │ • RBAC │ │ • OIDC │ │
│ └────────┬─────────┘ └────────┬─────────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────────┼─────────────────────┘ │
│ │ │
└──────────────────────────────────┼──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Data Layer │
│ (Port 5100-5499) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ PostgreSQL │ │ PostgreSQL │ │
│ │ Port 5432 │ │ (Telemetry) │ │ (Bookings) │ │
│ │ │ │ Port 5433 │ │ Port 5434 │ │
│ │ • Primary DB │ │ │ │ │ │
│ │ • Multi-tenant │ │ • Time-series │ │ • Domain DB │ │
│ │ • RBAC data │ │ • Event logs │ │ • Isolated │ │
│ └──────────────────┘ └──────────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Redis │ │ Redis (Cache) │ │
│ │ Port 6379 │ │ Port 6380 │ │
│ │ │ │ │ │
│ │ • Session store │ │ • Telemetry │ │
│ │ • Cache │ │ • Rate limiting │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ AI/ML Services │
│ (Port 8000-8999) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ BACH Chatbot (Port 8000) │ │
│ │ FastAPI • LLM integration • Context-aware assistance │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Service Details
Frontend Applications (3000-3999)
StackExplorer (Port 3000)
- Technology: Next.js 15, TypeScript, Tailwind CSS
- Purpose: Self-documenting developer portal
- Features:
- Interactive documentation
- API explorer with real-time testing
- Code examples and tutorials
- BACH AI chatbot integration
- Telemetry tracking
- Status: ✅ Active
- URL: http://localhost:3000
Bookings App (Port 3001)
- Technology: Next.js 15, TypeScript
- Purpose: Reference multi-tenant booking application
- Features:
- Complete RBAC implementation
- Multi-tenant data isolation
- Real-world business logic
- Best practices showcase
- Status: 🔜 Planned
- URL: http://localhost:3001
Platform Services (4000-4999)
App Launcher (Port 4000)
- Technology: Next.js 15, TypeScript
- Purpose: Central portal for all EASE applications
- Features:
- App registry with health monitoring
- Service discovery
- Single sign-on (SSO) integration
- Dashboard with quick access
- Status: ✅ Active
- URL: http://localhost:4000
Observability Dashboard (Port 4001)
- Technology: Next.js 15, React, TypeScript
- Purpose: Real-time monitoring and analytics
- Features:
- Live event streaming (5s refresh)
- Multi-tenant event filtering
- Statistics and metrics
- Search and analytics
- Color-coded event types
- Status: ✅ Active
- URL: http://localhost:4001
Telemetry Service (Port 4002)
- Technology: .NET Core 8, PostgreSQL, WebSocket
- Purpose: Centralized telemetry collection
- Features:
- Event ingestion API
- PostgreSQL time-series storage
- WebSocket real-time streaming
- Multi-tenant isolation
- API key authentication
- Status: 🔜 Planned
- URL: http://localhost:4002
Backend APIs (5000-5999)
StackExplorer API (Port 5001)
- Technology: .NET Core 8, Oracle/PostgreSQL
- Purpose: Backend for StackExplorer documentation
- Features:
- RESTful API
- Swagger/OpenAPI documentation
- Health check endpoints
- Telemetry API (temporary)
- Status: ✅ Active
- URL: http://localhost:5001
Bookings API (Port 5002)
- Technology: .NET Core 8, EASE Framework
- Purpose: Reference booking service
- Features:
- Multi-tenant CRUD operations
- RBAC implementation
- Audit logging
- Event publishing
- Status: 🔜 Planned
- URL: http://localhost:5002
Data Layer (5100-5499)
PostgreSQL Primary (Port 5432)
- Purpose: Main application database
- Schema: Multi-tenant with tenant isolation
- Used by: StackExplorer, Auth Service
PostgreSQL Telemetry (Port 5433)
- Purpose: Telemetry and event logs
- Schema: Time-series optimized (TimescaleDB)
- Used by: Telemetry Service
Redis (Port 6379)
- Purpose: Cache and session store
- Used by: All services for caching
AI/ML Services (8000-8999)
BACH Chatbot (Port 8000)
- Technology: FastAPI (Python), LLM integration
- Purpose: AI-powered developer assistance
- Features:
- Natural language queries
- Code generation
- Documentation lookup
- Context-aware responses
- Status: ✅ Active
- URL: http://localhost:8000
Data Flow Patterns
Telemetry Data Flow
┌─────────────────┐
│ User Action │
│ (Click/View) │
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ TelemetryProvider │
│ (React Context) │
│ • Batches events │
│ • Adds context │
│ • tenant_id, user_id │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ POST /api/telemetry │
│ (Batch send) │
│ • app_id │
│ • tenant_id │
│ • user_id │
│ • event_type │
│ • event_data │
│ • timestamp │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ In-Memory Store │
│ (Max 1000 events) │
│ • Fast access │
│ • Demo purposes │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ GET /api/telemetry │
│ (5s polling) │
│ • Filtering │
│ • Pagination │
│ • Statistics │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Observability │
│ Dashboard │
│ • Real-time display │
│ • Auto-refresh │
└─────────────────────────┘
Authentication Flow (Planned)
┌──────────┐
│ User │
└─────┬────┘
│
▼
┌────────────────┐
│ App Launcher │
│ (SSO Portal) │
└───────┬────────┘
│
▼
┌─────────────────┐ ┌──────────────┐
│ Auth Service │─────▶│ PostgreSQL │
│ Port 5003 │ │ Users/Roles │
└───────┬─────────┘ └──────────────┘
│
├─ Generate JWT
│
▼
┌─────────────────┐
│ Frontend App │
│ (with token) │
└───────┬─────────┘
│
▼
┌─────────────────┐
│ Backend API │
│ (validates) │
└─────────────────┘
Docker Compose Configuration
All services are orchestrated using Docker Compose:
# docker-compose.yml structure services: # Frontend apps stackexplorer: ports: ["3000:3000"] depends_on: - postgres - redis - api # Platform services app-launcher: ports: ["4000:4000"] observability-dashboard: ports: ["4001:4001"] # Backend APIs api: ports: ["5001:5000"] environment: - DATABASE_URL - REDIS_URL # Databases postgres: ports: ["5432:5432"] volumes: - postgres-data:/var/lib/postgresql/data redis: ports: ["6379:6379"] # AI Services chatbot: ports: ["8000:8000"]
Network Architecture
Internal Communication (Docker Network)
stackexplorer-network (Bridge)
├── stackexplorer:3000
├── api:5000 (exposed as 5001)
├── postgres:5432
├── redis:6379
└── chatbot:8000
Services communicate using Docker network DNS:
http://api:5000(internal)http://postgres:5432(internal)http://redis:6379(internal)
External Access (Host)
Exposed ports accessible from localhost:
- Frontend: 3000-3099
- Platform: 4000-4099
- Backend: 5001-5099
- Database: 5432 (dev only)
Scaling Strategy
Horizontal Scaling
Load Balancer (nginx/traefik)
│
├─ stackexplorer-1 (3000)
├─ stackexplorer-2 (3000)
└─ stackexplorer-3 (3000)
Service Independence
Each service can scale independently:
- Frontend apps: Stateless, scale freely
- Backend APIs: Stateless with shared DB/cache
- Databases: Primary-replica setup
- Cache: Redis cluster mode
Multi-Tenancy Architecture
Data Isolation
-- All tables include tenant_id CREATE TABLE bookings ( id UUID PRIMARY KEY, tenant_id UUID NOT NULL, -- Partition key user_id UUID NOT NULL, ... ); -- Row-level security CREATE POLICY tenant_isolation ON bookings FOR ALL USING (tenant_id = current_tenant_id());
Tenant Context Flow
Request → JWT (tenant_id) → Middleware → Query Filter
↓
tenant_id = 'xxx'
Security Architecture
Authentication
- JWT tokens with claims (tenant_id, user_id, roles)
- API keys for service-to-service
- OAuth2/OIDC for SSO
Authorization
- RBAC (Role-Based Access Control)
- Tenant isolation at database level
- Resource-level permissions
Network Security
- Internal Docker network for service communication
- TLS/SSL for external traffic (production)
- API rate limiting via Redis
- CORS configuration per service
Monitoring & Observability
Current Implementation
-
Telemetry Tracking
- Client-side event capture
- Automatic link tracking
- Page view tracking
- API call monitoring
-
Health Checks
/api/healthon all services- Database connectivity
- Redis availability
- Service status
-
Logging
- Structured JSON logs
- Tenant context in all logs
- Centralized via telemetry service
Planned Enhancements
- Distributed tracing (OpenTelemetry)
- Metrics collection (Prometheus)
- Alerting (when service down)
- Performance monitoring (APM)
Deployment Environments
Development
- Docker Compose
- Hot reload enabled
- Debug logging
- Local databases
Staging
- Kubernetes/Docker Swarm
- Production-like data
- Integration testing
- Performance testing
Production
- Kubernetes cluster
- Auto-scaling
- Load balancing
- High availability
- Backup & recovery
Getting Started
Prerequisites
- Docker & Docker Compose
- Node.js 18+
- .NET 8 SDK (for local dev)
Quick Start
# Clone repository git clone https://github.com/your-org/ease.git # Start all services cd ease/stackexplorer docker-compose up -d # Start platform services (local dev) cd ../app-launcher PORT=4000 npm run dev cd ../observability-dashboard PORT=4001 npm run dev # Access services open http://localhost:4000 # App Launcher open http://localhost:3000 # StackExplorer open http://localhost:4001 # Observability
Port Reference
| Range | Purpose | Examples |
|---|---|---|
| 3000-3999 | Frontend Applications | StackExplorer (3000), Bookings (3001) |
| 4000-4999 | Platform Services | App Launcher (4000), Observability (4001) |
| 5000-5999 | Backend APIs | APIs (5001+) |
| 5100-5499 | Databases | PostgreSQL (5432+) |
| 6000-6999 | Cache/Queue | Redis (6379+) |
| 8000-8999 | AI/ML Services | BACH (8000) |
Related Documentation
- Architecture Overview - High-level architecture concepts
- Multi-Tenancy - Tenant isolation patterns
- Security - Security best practices
- API Documentation - Interactive API testing
- Getting Started - Quick start guide
Status Legend
- ✅ Active: Service is running and production-ready
- 🔜 Planned: Service is designed and scheduled
- 🔄 In Progress: Service is under development
- 📋 Reserved: Port/service reserved for future use
Last Updated: November 10, 2025 Version: 1.0.0 Maintained by: EASE Platform Team