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.