🏗️ Architecture Overview
System Overview
┌─────────────────────────────────────────────────────────────┐
│ CLIENTS │
│ (Web App, Mobile App, Admin Portal) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ EDGE CACHE (optional) │
│ Cloudflare Workers + KV Store │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ EXPRESS BACKEND │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Cache │ │ API │ │ Core │ │ Integr. │ │
│ │Middleware│→ │ Routes │→ │ Services │→ │ Clients │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────────┐
│ PostgreSQL │ │ External Services │
│ + Prisma │ │ ┌───────┐ ┌─────┐ │
└─────────────────┘ │ │sevDesk│ │evcc │ │
│ └───────┘ └─────┘ │
│ ┌───────┐ ┌─────┐ │
│ │MS Graph│ │ista│ │
│ └───────┘ └─────┘ │
└─────────────────────┘
Layer Architecture
1. API Layer (src/api/)
- Express Router
- Request Validation
- Response Formatting
- Error Handling
2. Core Layer (src/core/)
- Business Logic
- Service Classes
- Type Definitions
- Cache Management
3. Integration Layer (src/integrations/)
- External API Clients
- Data Transformation
- Error Handling
4. Data Layer (prisma/)
- Database Schema
- Migrations
- Prisma Client
Multi-Tenant Architecture
┌─────────────────────────────────────────┐
│ Request │
│ Header: X-Tenant-ID: tenant-abc │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Tenant Middleware │
│ - Extract Tenant ID │
│ - Validate Access │
│ - Inject into Context │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ Service │
│ - Filter by tenantId │
│ - Enforce Data Isolation │
└─────────────────────────────────────────┘
Data Model
Tenant
├── Properties
│ └── Units
│ ├── Contracts
│ └── Meters
│ └── MeterReadings
└── Users
Request Flow
1. Client Request
↓
2. Cache Middleware (Check HIT/MISS)
↓
3. Route Handler
↓
4. Service Method
↓
5. Prisma Query / Integration Client
↓
6. Response (+ Cache Store)
Tech Stack
| Layer |
Technology |
| Runtime |
Node.js 20+ |
| Framework |
Express.js |
| Language |
TypeScript 5.x |
| Database |
PostgreSQL |
| ORM |
Prisma |
| Cache |
Memory / Redis / CF KV |
| Testing |
Vitest |
| Edge |
Cloudflare Workers |