ems-core/README.md

EMS Core Platform (ems-core)

Backend + shared libraries for all EMS customer projects

Current Version: 1.2.0 (see VERSIONS.json)

ems-core is the shared backend core for all EMS deployments. It provides the FastAPI backend, database models, data collectors, and customer hooks system. Frontend and Nginx are NOT included -- each customer repo provides its own frontend.

---

System Architecture

          +--------------------+
          |    Backend (Core)  |
          |    FastAPI         |
          |    :8000           |
          |    /api/v1/*       |
          +--------+-----------+
                   |
       +-----------+-----------+
       |                       |
+------v------+         +------v-------+
| TimescaleDB |         |    Redis     |
| PostgreSQL  |         |   Cache/Queue|
|   :5432     |         |   :6379      |
+-------------+         +--------------+

Note: Frontend and Nginx are NOT part of ems-core.
Each customer repo provides its own frontend and reverse proxy.

---

Tech Stack

Layer	Technology
Backend	FastAPI (Python 3.11)
ORM	SQLAlchemy 2.0 (async)
Database	TimescaleDB (PostgreSQL 16)
Cache	Redis 7
Task Queue	Celery + APScheduler
Migrations	Alembic
Container	Docker + Docker Compose

---

Quick Start

Prerequisites

• Docker 20.10+
• Docker Compose 2.0+

Start Services

# Clone
git clone http://100.69.143.96:3300/tianpu/ems-core.git
cd ems-core

# Configure
cp .env.example .env

# Start all services
docker compose up -d

# Initialize database
docker compose exec backend python scripts/init_db.py

Or use the quick-start script:

bash scripts/quick-start.sh

Access

Service	URL
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
Health Check	http://localhost:8000/health

Default Login

Role	Username	Password
Admin	admin	admin123

Change the default password after first login.

---

Local Development

cd backend

# Create venv
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install deps
pip install -r requirements.txt

# Start dev server (requires PostgreSQL and Redis running)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Start only infrastructure:

docker compose up -d postgres redis

---

Project Structure

ems-core/
+-- backend/                    # Backend service
|   +-- app/
|   |   +-- api/v1/            # API routes
|   |   +-- collectors/        # Data collectors (Sungrow, Modbus, MQTT, HTTP)
|   |   +-- core/              # Core config
|   |   +-- hooks/             # Customer plugin system
|   |   +-- models/            # SQLAlchemy ORM models
|   |   +-- services/          # Business logic
|   |   +-- tasks/             # Background tasks (Celery + APScheduler)
|   |   +-- templates/         # Email templates
|   |   +-- main.py            # App entry point
|   +-- alembic/               # Database migrations
|   +-- tests/                 # Test suite
|   +-- Dockerfile
|   +-- requirements.txt
+-- scripts/                   # Utility scripts
|   +-- init_db.py             # Database initialization
|   +-- backfill_data.py       # Historical data backfill
|   +-- quick-start.sh         # Quick start script
+-- docker-compose.yml         # Dev environment
+-- docker-compose.prod.yml    # Production environment
+-- VERSION                    # Version file
+-- VERSIONS.json              # Version metadata
+-- .env.example               # Environment variables template
+-- CLAUDE.md                  # AI assistant guidelines
+-- README.md

---

API Endpoints

Main modules:

• /api/v1/auth -- Authentication
• /api/v1/devices -- Device management
• /api/v1/energy -- Energy data
• /api/v1/carbon -- Carbon emissions
• /api/v1/alarms -- Alarm management
• /api/v1/reports -- Reports
• /api/v1/system -- System management

Full Swagger docs at http://localhost:8000/docs after starting the backend.

---

Note

ems-core is the backend-only shared library. Each customer project (tp-ems, zpark-ems) owns its own frontend, deployed independently.

---

License

Copyright 2026. All rights reserved.