boc/aamos-reusability-analysis.md

# AAMOS Infrastructure Reusability Analysis for LandveX Enterprise Platform

**Date:** 2026-07-02
**Analyst:** OpenClaw Subagent
**Scope:** Identify reusable components across AAMOS ecosystem for LandveX Enterprise Platform

---

## Executive Summary

The AAMOS ecosystem contains **5 major codebases** with varying maturity levels:
1. **aamos-ledger** (Node.js/Express) — Production-ready ledger engine
2. **aamos-ledger-rust** (Rust/Axum) — Next-gen rewrite in progress
3. **iom** (Python/FastAPI) — Infrastructure Object Model platform
4. **quixzoom-capture-pipeline** (Node.js) — Data collection & AI pipeline
5. **ouroboros-frontend** (React/Vite/TS) — Modern frontend framework

**Key Finding:** Strong architectural convergence around PostgreSQL + Redis + JWT auth + event-driven patterns. The Rust ledger rewrite and IOM platform represent the most mature, reusable foundations.

---

## 1. Auth/Identity Service

### 1.1 aamos-ledger (Node.js) — auth.mjs
| Aspect | Detail |
|--------|--------|
| **Current Usage** | JWT validation (RS256/HS256), RBAC (admin/accountant/viewer), tenant isolation, service-to-service tokens |
| **Implementation** | Express middleware, role hierarchy, tenant matching, JWT claims validation |
| **Reusability** | **Medium** — Well-structured but Node.js/Express-specific. Role hierarchy is hardcoded for finance. |
| **Adaptation Cost** | **Medium** — Needs abstraction for LandveX roles (municipality, property_owner, infrastructure_owner, etc.). Tenant isolation logic is reusable. |

### 1.2 aamos-ledger-rust (Rust) — aamos-auth crate
| Aspect | Detail |
|--------|--------|
| **Current Usage** | JWT validation (HS256/RS256), HashSet-based roles, Axum middleware integration |
| **Implementation** | `JwtValidator` struct, `AuthUser` with `has_role`/`has_any_role`, `require_role!` macro |
| **Reusability** | **High** — Clean separation, generic enough for any role set. Axum middleware pattern is framework-agnostic within Rust ecosystem. |
| **Adaptation Cost** | **Low** — Add LandveX-specific roles to `Role` enum. Macro-based middleware is easily extensible. |

### 1.3 IOM (Python/FastAPI) — auth.py
| Aspect | Detail |
|--------|--------|
| **Current Usage** | JWT with role-permission mapping (UserRole enum + Permission enum), `AuthManager` class |
| **Implementation** | `ROLE_PERMISSIONS` dict maps roles to granular permissions. FastAPI dependency injection. |
| **Reusability** | **High** — Most sophisticated permission model. Role→permission mapping is exactly what LandveX plugin architecture needs. |
| **Adaptation Cost** | **Low** — Add LandveX roles/permissions. FastAPI dependencies are clean and reusable. |

### 1.4 quixzoom-capture-pipeline
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Basic JWT (implied by server.js comments), no dedicated auth module found |
| **Reusability** | **Low** — Not a reference implementation for auth. |

### Auth Recommendation
**Primary:** IOM `auth.py` — most complete RBAC+permission model, directly aligns with LandveX plugin permission manifest requirements.
**Secondary:** aamos-ledger-rust `aamos-auth` — if Rust stack is chosen for performance-critical paths.

---

## 2. API Gateway

### 2.1 aamos-ledger (Node.js/Express)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Express app with helmet, cors, rate-limiting, auth middleware, tenant context |
| **Implementation** | Middleware chain: helmet → cors → rateLimit → auth → tenant → routes |
| **Reusability** | **Medium** — Express-specific. Middleware pattern is standard but not framework-agnostic. |
| **Adaptation Cost** | **Medium** — Would need porting to chosen framework (Axum/FastAPI/Express). |

### 2.2 aamos-ledger-rust (Rust) — aamos-api crate
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Axum router with Tower layers (CorsLayer, TraceLayer), state injection |
| **Implementation** | `AppState` struct with pool/jwt/audit/hermes. `routes::create_router()` pattern. |
| **Reusability** | **High** — Tower/Axum is the modern Rust standard. Layer-based middleware is composable and testable. |
| **Adaptation Cost** | **Low** — Add LandveX-specific routes. State pattern easily extended with plugin manager. |

### 2.3 IOM (Python/FastAPI)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | FastAPI with CORS, HTTPBearer auth, dependency injection, WebSocket support |
| **Implementation** | `FastAPI()` app with middleware, `Depends()` for auth, `ConnectionManager` for WS |
| **Reusability** | **High** — FastAPI's dependency injection is excellent for plugin architecture. Auto-generated OpenAPI docs. |
| **Adaptation Cost** | **Low** — Plugin routes can be dynamically mounted. WebSocket manager reusable for real-time features. |

### 2.4 IOM — nginx
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Reverse proxy, rate limiting (per endpoint), SSL termination, upstream to API |
| **Implementation** | `nginx.conf` with `limit_req_zone`, upstream blocks, health checks |
| **Reusability** | **High** — Generic, production-ready. Directly reusable for LandveX. |
| **Adaptation Cost** | **Low** — Update upstream names and SSL certs. |

### 2.5 quixzoom-capture-pipeline
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Express with helmet, cors, rate-limit, Redis-backed queue stats |
| **Reusability** | **Medium** — Similar to aamos-ledger but less mature. WebSocket server is specialized for fleet intelligence. |

### API Gateway Recommendation
**Primary:** IOM FastAPI + nginx — proven pattern, excellent plugin support via dynamic route mounting.
**Alternative:** aamos-ledger-rust Axum/Tower — if Rust is chosen for performance. Both are valid; FastAPI has faster development velocity.

---

## 3. Database Layer

### 3.1 aamos-ledger (Node.js) — pg + schema.sql
| Aspect | Detail |
|--------|--------|
| **Current Usage** | PostgreSQL with ledger_accounts, ledger_journal_entries, ledger_journal_lines, ledger_audit_log, ledger_periods |
| **Implementation** | `pg.Pool`, parameterized queries, schema with constraints, indexes, sequences |
| **Reusability** | **High** — Schema design is excellent: tenant isolation, audit trail, immutable journal entries, period management. |
| **Adaptation Cost** | **Low-Medium** — Core tables reusable for LandveX billing (customers→organizations, contracts, invoices). Needs extension for plugin data. |

### 3.2 aamos-ledger-rust (Rust) — aamos-db + sqlx
| Aspect | Detail |
|--------|--------|
| **Current Usage** | `PgPoolOptions`, sqlx migrations, compile-time query checking |
| **Implementation** | `create_pool()` with max_connections, acquire_timeout, idle_timeout. Migration runner. |
| **Reusability** | **High** — sqlx provides type-safe queries. Migration system is standard. |
| **Adaptation Cost** | **Low** — Pool configuration is generic. Migrations need LandveX-specific tables. |

### 3.3 IOM (Python) — asyncpg
| Aspect | Detail |
|--------|--------|
| **Current Usage** | `DatabasePool` with asyncpg, connection pooling, health checks, transactions |
| **Implementation** | `asyncpg.create_pool`, `@asynccontextmanager` for acquire, `fetch`/`fetchrow`/`execute` methods |
| **Reusability** | **High** — Clean abstraction. PostGIS support for geospatial data. |
| **Adaptation Cost** | **Low** — Pool wrapper is generic. Add LandveX schema tables. |

### 3.4 quixzoom-capture-pipeline
| Aspect | Detail |
|--------|--------|
| **Current Usage** | PostgreSQL + PostGIS, Neo4j for knowledge graph, Redis for caching |
| **Implementation** | Multi-database setup in docker-compose |
| **Reusability** | **Medium** — PostGIS is relevant for LandveX (property locations, maps). Neo4j adds complexity. |
| **Adaptation Cost** | **Medium** — Multi-database orchestration needed. Neo4j may be overkill initially. |

### Database Recommendation
**Primary:** aamos-ledger schema + IOM asyncpg pool — combine the excellent ledger schema design with IOM's clean Python async wrapper.
**For geospatial:** Add PostGIS (from QuixZoom/IOM pattern) for property/GIS features.

---

## 4. Event Bus

### 4.1 aamos-ledger (Node.js) — hermes.mjs
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Redis pub/sub primary, JSONL file fallback, event envelope with trace/correlation/tenant |
| **Implementation** | `emit()` publishes to Redis + appends to JSONL. `subscribe()` for consumers. Lazy Redis connection. |
| **Reusability** | **High** — Event envelope structure is well-designed (trace_id, correlation_id, tenant_id, decision_source). JSONL fallback is robust. |
| **Adaptation Cost** | **Low** — Event types need LandveX namespacing (`landvex.billing.invoice.created`). Core logic reusable. |

### 4.2 aamos-ledger-rust (Rust) — aamos-hermes
| Aspect | Detail |
|--------|--------|
| **Current Usage** | `HermesEvent` struct, `HermesClient` trait, `RedisHermes` implementation |
| **Implementation** | Async trait for emit, Redis PUBLISH with JSON serialization |
| **Reusability** | **High** — Trait-based design allows multiple backends (Redis, Kafka, in-memory for testing). |
| **Adaptation Cost** | **Low** — Implement trait for LandveX event types. Add consumer pattern if needed. |

### 4.3 IOM (Python) — event_bus.py
| Aspect | Detail |
|--------|--------|
| **Current Usage** | In-memory event bus with asyncio, subscriber registry, event history |
| **Implementation** | `EventBus` class with `subscribe`/`publish`/`get_events`. Enum-based event types. |
| **Reusability** | **Medium** — In-memory only, no persistence. Good for single-process, not distributed. |
| **Adaptation Cost** | **Medium** — Needs Redis/RabbitMQ backend for production. Event type enum is reusable. |

### 4.4 quixzoom-capture-pipeline
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Redis for queues (AI, taxonomy, dataset), implied event flow |
| **Reusability** | **Low-Medium** — Queue-based, not event-bus patterned. Kafka mentioned in docker-compose but not in code. |

### Event Bus Recommendation
**Primary:** aamos-ledger hermes.mjs — most production-ready with Redis + JSONL fallback. Event envelope structure directly supports audit and traceability requirements.
**Alternative:** aamos-ledger-rust aamos-hermes — if Rust stack chosen. Trait design is more extensible.

---

## 5. Frontend Framework

### 5.1 ouroboros-frontend (React/Vite/TS)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | React 19 + Vite + TypeScript + Tailwind CSS + React Router |
| **Implementation** | Modern SPA setup with AuthContext, API client, type definitions |
| **Reusability** | **High** — Modern, standard stack. AuthContext pattern reusable. API client (`fetchWithAuth`) is generic. |
| **Adaptation Cost** | **Low** — Replace mock auth with real JWT flow. Add LandveX-specific routes/views. Tailwind theming for LandveX brand. |

### 5.2 landvex-admin (HTML/CSS/JS)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Dark-themed admin dashboard, city grid UI, inline CSS/JS |
| **Implementation** | Single HTML file with CSS custom properties, vanilla JS |
| **Reusability** | **Medium** — UI components (cards, tabs, modals, toasts) are well-designed. But monolithic structure. |
| **Adaptation Cost** | **Medium** — Extract components into reusable form. Dark theme aligns with LandveX brand. |

### 5.3 landvex-finance-sprint3 (Vanilla JS ES Modules)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | Vanilla JS with ES modules, state management, lazy-loaded tabs |
| **Implementation** | `state.mjs` (Redux-like), `api.mjs` (fetch wrapper), `main.mjs` (tab routing), period management |
| **Reusability** | **Medium** — State management pattern is clean. But vanilla JS doesn't scale as well as React for complex UIs. |
| **Adaptation Cost** | **Medium** — Could port state logic to React context. API layer is reusable. |

### 5.4 aamos-ledger UI (Vanilla JS)
| Aspect | Detail |
|--------|--------|
| **Current Usage** | `API` class, `Router` class, app shell with tabs |
| **Implementation** | Simple class-based API client, hash-based router |
| **Reusability** | **Low-Medium** — Basic patterns, but less sophisticated than sprint3 or React. |

### Frontend Recommendation
**Primary:** ouroboros-frontend (React/Vite/TS) — modern, typed, component-based. Aligns with LandveX billing DESIGN.md which specifies React/Vue.
**Component library:** Extract reusable patterns from landvex-admin (dark theme, card layouts, form components) into React components.

---

## Cross-Cutting Concerns

### Tenant Isolation (ARC-003)
All mature codebases implement tenant isolation:
- **aamos-ledger:** `tenant_id` in every table, RLS policies, middleware validation
- **aamos-ledger-rust:** `TenantId` newtype, tenant in JWT claims
- **IOM:** Multi-tenant via `tenant_id` (implied by auth patterns)
- **ARC-003 standard:** Formalizes RLS, Redis key-prefixing, event envelope tenant field

**Reusability:** **Very High** — ARC-003 is a platform standard. Implementation patterns are consistent across codebases.

### Canonical Domain Model (ARC-001)
Twelve universal objects defined (Entity, Organization, Person, Asset, Location, Project, Task, Workflow, Document, Transaction, Event, Contract).

**Reusability:** **Very High** — LandveX billing's `customers`, `contracts`, `invoices` map directly to `Organization`, `Contract`, `Document`+`Transaction`.

### Audit & Observability
- **aamos-ledger:** `ledger_audit_log` (append-only), trace_id/correlation_id, decision_source
- **aamos-ledger-rust:** `AuditWriter` crate
- **IOM:** Structured logging, Prometheus metrics, Grafana dashboards
- **landvex-finance-sprint3:** `metrics.mjs`, `logger.mjs`, `health.mjs`

**Reusability:** **High** — Patterns are consistent. Prometheus metrics and structured logging directly reusable.

---

## Summary Matrix

| Component | Best Implementation | Reusability | Adaptation Cost | Notes |
|-----------|---------------------|-------------|-----------------|-------|
| **Auth/Identity** | IOM `auth.py` | High | Low | Role-permission model fits plugin architecture |
| **API Gateway** | IOM FastAPI + nginx | High | Low | Dynamic route mounting for plugins |
| **Database Layer** | aamos-ledger schema + IOM asyncpg | High | Low-Medium | Excellent schema design, clean Python wrapper |
| **Event Bus** | aamos-ledger hermes.mjs | High | Low | Redis+JSONL fallback, great envelope design |
| **Frontend** | ouroboros-frontend (React/Vite/TS) | High | Low | Modern stack, type-safe |
| **Tenant Isolation** | ARC-003 standard | Very High | Low | Formalized across all layers |
| **Domain Model** | ARC-001 standard | Very High | Low | 12 canonical objects |
| **Audit/Observability** | Combined from ledger + IOM | High | Low | Prometheus, structured logs, health checks |

---

## Recommended Architecture for LandveX Enterprise Platform

Based on this analysis, the optimal reuse strategy:

```
┌─────────────────────────────────────────────────────────────┐
│                    LANDVEX ENTERPRISE PLATFORM               │
├─────────────────────────────────────────────────────────────┤
│  FRONTEND: ouroboros-frontend (React/Vite/TS)              │
│  ├── AuthContext → extend with real JWT flow               │
│  ├── API client → reuse fetchWithAuth pattern              │
│  └── Components → merge landvex-admin dark theme           │
├─────────────────────────────────────────────────────────────┤
│  API GATEWAY: IOM FastAPI + nginx                          │
│  ├── Auth → IOM auth.py (role-permission model)            │
│  ├── Routes → dynamic mounting for plugins                 │
│  └── WebSocket → IOM ConnectionManager                     │
├─────────────────────────────────────────────────────────────┤
│  DATABASE: PostgreSQL + PostGIS                            │
│  ├── Schema → aamos-ledger schema as base                  │
│  ├── Pool → IOM DatabasePool (asyncpg)                     │
│  └── Migrations → sqlx or alembic pattern                  │
├─────────────────────────────────────────────────────────────┤
│  EVENT BUS: Hermes (aamos-ledger pattern)                  │
│  ├── Redis pub/sub primary transport                       │
│  ├── JSONL fallback for durability                         │
│  └── Event envelope → trace/correlation/tenant             │
├─────────────────────────────────────────────────────────────┤
│  PLUGIN SYSTEM: New development                            │
│  ├── Sandbox → WebAssembly or containers                   │
│  ├── API Layer → TypeScript interfaces (from spec)         │
│  └── Registry → npm-like package management                │
├─────────────────────────────────────────────────────────────┤
│  INFRASTRUCTURE:                                           │
│  ├── Docker Compose → based on IOM/quixzoom patterns       │
│  ├── Monitoring → Prometheus + Grafana (from IOM)          │
│  └── Logging → structured JSON (from sprint3 logger)       │
└─────────────────────────────────────────────────────────────┘
```

---

## Risk Assessment

| Risk | Mitigation |
|------|------------|
| Multiple auth implementations (Node/Rust/Python) | Standardize on IOM's role-permission model |
| Rust rewrite incomplete | Keep Node.js ledger as fallback; don't block on Rust |
| Frontend fragmentation (3+ approaches) | Commit to React/Vite; deprecate vanilla JS UIs |
| Database schema divergence | Enforce ARC-001 canonical model |
| Event bus inconsistency | Standardize on Hermes envelope format |

---

*Analysis complete. All major components evaluated against 5 focus areas with reusability ratings and adaptation cost estimates.*