Eco Manager Wiki

Appearance

Architecture Overview ​

Architecture Style ​

Eco Manager uses a contract-driven modular monolith.

The system is deployed as one backend application, but internally organised into clear vertical modules. Shared contracts and database schema live in workspace packages so the backend and frontend apps can share types safely.

Monorepo Layout ​

text
.
├── apps/
│   ├── backend/
│   ├── frontend/
│   └── admin/
│
├── packages/
│   ├── contracts/
│   ├── db/
│   ├── auth/
│   ├── permissions/
│   └── shared/
│
└── docs/

Apps ​

Backend ​

The backend is a Hono application running on Bun.

Responsibilities:

  • API routing,
  • authentication integration,
  • authorisation checks,
  • application services,
  • database transactions,
  • audit events,
  • Vault operations,
  • integration webhooks.

Backend modules are vertical slices. A module owns its routes, services, validators, permissions, and use cases.

Frontend ​

The main frontend is the engineer and operations UI.

Responsibilities:

  • customer/site/building/asset navigation,
  • asset management workflows,
  • credential workflows,
  • commissioning workflows,
  • remote access workflows,
  • operational dashboards.

Admin Studio ​

The Admin Studio app is the super-user CRUD/configuration UI for the Universal Entity Platform.

Responsibilities:

  • manage entity types,
  • manage entities,
  • manage hierarchy,
  • manage property groups and property definitions,
  • manage tag groups and tags,
  • manage entity groups,
  • manage templates,
  • inspect relationships,
  • inspect audit events,
  • perform guarded bulk operations.

Admin Studio shares contracts with the backend, but it should have its own frontend application boundary because its information architecture, risk profile, and user experience are different from the normal engineer-facing product.

Contracts Package ​

The contracts package contains pure TypeScript and Zod.

It may contain:

  • request schemas,
  • response schemas,
  • DTOs,
  • route contract definitions,
  • shared enum-like constants,
  • validation helpers.

It must not contain:

  • Drizzle schema,
  • database queries,
  • backend services,
  • secrets,
  • environment-specific code.

Database Package ​

The database package contains Drizzle schema, relations, migrations, seed scripts, and database connection helpers.

It may contain:

  • table definitions,
  • relations,
  • migrations,
  • seed data,
  • reusable database type exports.

It should not contain business workflows.

Core Architectural Primitive ​

The Universal Entity Platform is the foundation.

Most business objects are represented as entities with:

  • type,
  • hierarchy position,
  • path,
  • property groups,
  • tags,
  • groups,
  • relationships,
  • audit events,
  • permissions.

Domain-specific modules such as Customers, Sites, Buildings, Assets, Credentials, Vault, Remote Connectivity, and Simpro Integration build on top of this foundation.

Security Architecture Direction ​

Eco Manager should enforce authorization through reusable root-entity scoping and protect sensitive values with tenant/root-level encryption boundaries. Application services should check that a target entity is inside the user's allowed root entity tree before allowing edits, secret access, remote sessions, or audit access.