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

```bash
# 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
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

```bash
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:

```bash
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](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.