Monorepo consolidation: workspace, shared types, transport plans, docker/swam assets

aggregate/README.md

@@ -0,0 +1,81 @@
+# aggregate
+
+## Running
+
+### Configuration
+
+Configuration is loaded in this order:
+
+1. If `AGGREGATE_CONFIG_PATH` is set and points to a readable config file, load that file and apply env overrides.
+2. Otherwise load defaults and apply env overrides.
+
+Supported config formats:
+- YAML (`.yaml`, `.yml`)
+- TOML (`.toml`)
+- JSON (`.json`)
+
+### Environment Variables
+
+#### Core
+- `AGGREGATE_NATS_URL` (default: `nats://localhost:4222`): NATS server URL.
+- `AGGREGATE_STORAGE_PATH` (default: `./data`): Path used by the snapshot storage.
+- `AGGREGATE_SNAPSHOT_THRESHOLD` (default: `10`): Save snapshot when events since last snapshot reach this threshold.
+- `AGGREGATE_MAX_RETRIES` (default: `3`): Max retries for version conflicts in command handling.
+- `AGGREGATE_HTTP_ADDR` (default: `0.0.0.0:8080`): HTTP bind address.
+- `AGGREGATE_GRPC_ADDR` (default: `0.0.0.0:50051`): gRPC bind address for command submission.
+
+#### Multi-tenant
+- `AGGREGATE_MULTI_TENANT` (default: `true`): Enables multi-tenant behavior when parsing/validating tenant ids.
+- `AGGREGATE_DEFAULT_TENANT_ID` (default: unset): Default tenant id when the incoming request doesn't specify one.
+- `AGGREGATE_SHARD_ID` (default: `local`): Shard id used when applying placement maps.
+
+#### Logging
+- `AGGREGATE_LOGGER_SOCKET` (default: unset): Socket path for `edge-logger-client` integration (if enabled).
+
+#### Server
+- `AGGREGATE_CONFIG_PATH` (default: unset): Path to a YAML/TOML/JSON config file.
+
+#### Placement
+- `AGGREGATE_PLACEMENT_BUCKET` (default: `AGGREGATE_PLACEMENT`): NATS KV bucket to watch.
+- `AGGREGATE_PLACEMENT_KEY` (default: `aggregate_placement`): NATS KV key to watch. Value is a JSON object mapping `tenant_id -> shard_id`.
+
+#### Runtime Programs
+- `AGGREGATE_DECIDE_PROGRAM` / `AGGREGATE_APPLY_PROGRAM`: Inline program source strings.
+- `AGGREGATE_DECIDE_PROGRAM_PATH` / `AGGREGATE_APPLY_PROGRAM_PATH`: File paths to program source strings.
+
+## HTTP Endpoints
+
+- `GET /health` → JSON health report
+- `GET /ready` → JSON boolean readiness
+- `GET /metrics` → Prometheus text format
+- `GET /admin/tenants` → JSON list of hosted tenants
+- `POST /admin/drain` → marks tenant draining and waits for in-flight commands to finish (`{"tenant_id":"..."}`)
+- `POST /admin/reload` → updates hosted tenant allowlist (`{"hosted_tenants":[...]}`) or applies a placement map (`{"placement":{...}}`)
+- `GET /admin/tenant/{tenant_id}/status` → JSON tenant status (`hosted`, `accepting`, `draining`, `in_flight`)
+- `GET /admin/tenant/{tenant_id}/ready` → JSON boolean (node ready AND accepting tenant)
+- `POST /admin/tenant/{tenant_id}/drain` → drains tenant with optional timeout (`{"timeout_ms":10000}`)
+
+## gRPC
+
+Aggregate exposes a command submission API for the Gateway:
+
+- Service: `aggregate.gateway.v1.CommandService`
+- Method: `SubmitCommand`
+- Metadata: `x-tenant-id` (tenant routing hint)
+
+Proto definition: [aggregate.proto](file:///Users/vlad/Developer/cloudlysis/aggregate/proto/aggregate.proto)
+
+## Container
+
+Build and run locally:
+
+```bash
+docker build -t cloudlysis/aggregate:local -f docker/Dockerfile.rust --build-arg PACKAGE=aggregate --build-arg BIN=aggregate .
+docker compose up -d --build
+```
+
+Container smoke test (requires Docker installed):
+
+```bash
+sh docker/scripts/verify_aggregate_container.sh
+```