🏗️ 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