Instance Workspace (Community Shop)

The Instance workspace contains all applications and packages related to local community shops. It is the primary focus of the Elo Orgânico monorepo, providing localized ecommerce, order logistics, payment systems, and administrative interfaces for individual agricultural community hubs.

Directory Structure

instance/
├── apps/
│   ├── api/          # Fastify 5 REST API
│   └── web/          # React 19 Single Page Application (SPA)
├── packages/
│   └── core/         # Shared Domain Model (SSOT)
├── compose.dev.yaml  # Developer container stack (MongoDB + Redis)
└── compose.prod.yaml # Production deployment container stack

Core Components & Architecture

@elo-instance/core (Domain SSOT)

All schema configurations, database models, validators, and core business policies are defined in this package. By forcing the API and any secondary tools to inherit definitions from this core layer, we enforce strict Bounded Context parity and prevent model duplication.

• Technology Stack: TypeScript, Mongoose, Zod.
• Key Files: Shared schema definitions for products, orders, cycles, users, and transactions.

@elo-instance/api (Fastify 5 Engine)

A high-performance REST API built with Fastify v5, implementing a decoupled, layered software architecture.

• Layered Design Flow: Controller ──> Service ──> Repository ──> Model
• Key Integrations:
  • Mongoose connection to the local/Atlas MongoDB database.
  • Redis cache managers for rate-limiting, session storage, and fast queries.
  • Zod validation hooks for incoming requests (body, query, params) and outgoing responses.
• Strict Guidelines:
  • All asynchronous operations must be explicitly handled. Unawaited promises must be prefixed with the void operator.
  • Strict boolean checks are enforced throughout the API controllers (if (value === true)).

@elo-instance/web (React 19 Portal)

The user and administrator storefront dashboard built on React 19 and compiled with Vite.

• Technology Stack: React 19, TypeScript, Vite, Zustand (state management), Studio Tokens (theme integration).
• Design Parity: Inherits theme variables, colors, and layout constants directly from the @elo-organico/studio package.
• React 19 Features: Implements modern React 19 standards, utilizing the use() hook for loading resource promises, and ensuring strict boolean comparisons in all JSX templates.

Infrastructure and Database Configuration

To support high-integrity financial operations (such as Pix confirmations and stock management during cycle closings), the local environment runs a Docker-orchestrated MongoDB replica set:

• Replica Set Name: rs0
• Initiator Service: db-init (in compose.dev.yaml) initializes the replica set configuration (rs.initiate()) after MongoDB is ready.
• Cache Layer: Redis container handles high-velocity key-value storage and rate limiting.

Workspace Scripts

Run these commands from the root directory to manage the Instance context:

Command	Action
pnpm instance:up	Spins up local database (MongoDB Replica Set) and Redis containers.
pnpm instance:dev	Runs the API server (via tsx watch) and Web client (via Vite dev server) concurrently.
pnpm instance:down	Stops and removes the Docker containers.
pnpm instance:prod	Builds and launches production container images using production environment settings.