ADR-0001: Use a Contract-Driven Modular Monolith

Date: 2026-06-06

Status: Accepted

Context

Eco Manager is being built by a very small team. The system needs to be easy to develop, easy to understand, and easy to change. It also needs strong typing between backend and frontend apps, a clear API boundary, and enough modularity to grow.

A microservices architecture would add deployment, networking, data consistency, observability, and operational complexity too early.

A single unstructured application would be fast initially but likely become hard to maintain as the product grows.

Decision

Eco Manager will use a contract-driven modular monolith.

The backend will be one deployable Hono application, organized internally into vertical modules.

Shared contracts will live in a pure TypeScript/Zod workspace package.

Database schema and migrations will live in a separate Drizzle workspace package.

Consequences

Positive

• Simple deployment.
• Strong type sharing between backend, frontend, and admin app.
• Clear module boundaries.
• Good developer experience for a small team.
• Easier refactoring than distributed services.

Negative

• Module boundaries require discipline.
• One backend deployment contains all backend modules.
• Future extraction into services would require deliberate work.

Trade-offs

This architecture prioritizes speed, maintainability, and type safety over independent service deployment.