Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• PLAN-TAMV-MODULAR.md
• 02_MODULOS/M05_IA_TAMVAI/INTERNO/QC-TAMV-01-v1.1.md
• scripts/check-architecture.ts
• README_TAMV_COMPLETO.md
• eslint-plugin-tamv/index.js
• supabase/functions/tamv-fusion-core/index.ts

The TAMV MD-X4 architecture, also known as the "Civilizatory Client," is a modular, high-integrity ecosystem designed for Mexican digital sovereignty. It integrates advanced frontend technologies (React, Three.js), a robust backend-as-a-service (Supabase), and a constitutional quality control framework (QC-TAMV-01) that ensures structural determinism and technical neutrality.

This architecture is governed by a set of "Invariant Laws" (L1–L9) that enforce strict separation of concerns between navigation, layout, business logic, and UI modules. The system is designed to be "Actor Neutral," meaning the same rules and automated enforcement mechanisms apply to both human developers and autonomous AI agents operating on the codebase.

Sources: 02_MODULOS/M05_IA_TAMVAI/INTERNO/QC-TAMV-01-v1.1.md:10-40, README_TAMV_COMPLETO.md:5-20

Core Structural Layers

The architecture is divided into five primary layers, each with specific responsibilities and restricted interactions to prevent architectural regression.

Layer	Responsibility	Key File/Path
Root/Entry	Application initialization and React mounting.	src/main.tsx
Router/App	Navigation control and global shell mounting.	src/App.tsx
Pages	Route-specific orchestrators that compose modules.	src/pages/*
Modules	Feature-encapsulated UI components, agnostic of navigation.	src/modules/*
Domains	Cross-cutting business abstractions (Auth, AI, XR).	src/domains/*

Sources: 02_MODULOS/M05_IA_TAMVAI/INTERNO/QC-TAMV-01-v1.1.md:42-55, scripts/check-architecture.ts:145-160

Dependency Flow and Constraints

The system architecture enforces a strict top-down dependency flow to ensure modularity and testability.

Constitutional Quality Control (QC-TAMV-01)

A defining feature of the TAMV architecture is the Constitutional Quality Control System. This framework translates architectural principles into executable code invariants enforced via ESLint and automated scripts.

The Invariant Laws (L1–L7)

The following laws are non-negotiable axioms that define technical validity:

1. L1 – Unique Root: ReactDOM.createRoot is restricted exclusively to src/main.tsx.
2. L2 – Unique Router: BrowserRouter is restricted exclusively to src/App.tsx.
3. L3 – Unique Layout: The Layout.tsx shell is mounted once in App.tsx.
4. L4 – Route-Page Correspondence: Each file in src/pages/ maps to one route; pages cannot import other pages.
5. L5 – Domain-Logic-Free Pages: Pages orchestrate modules but do not contain business logic or persistent side-effects.
6. L6 – Navigation-Agnostic Modules: Files in src/modules/ cannot import react-router-dom or pages.
7. L7 – Controlled Initialization: Global services (Supabase, AI) are initialized only in integrations/ or core/.

Sources: 02_MODULOS/M05_IA_TAMVAI/INTERNO/QC-TAMV-01-v1.1.md:60-95, eslint-plugin-tamv/index.js:15-180

Automated Enforcement Mechanisms

The architecture employs custom tooling to detect violations of these laws during development and CI/CD:

• eslint-plugin-tamv: A custom ESLint plugin that blocks illegal imports (e.g., tamv/no-router-in-modules).
• scripts/check-architecture.ts: A dependency graph analyzer that detects structural regressions like page -> page imports.
• tamv-fusion-core: A backend orchestrator (Edge Function) that performs health checks across critical routes and database tables.

Sources: eslint-plugin-tamv/index.js:380-410, scripts/check-architecture.ts:10-40, supabase/functions/tamv-fusion-core/index.ts:15-35

Backend & Integration Architecture

The TAMV backend utilizes Supabase (PostgreSQL + Edge Functions) as its core infrastructure. It is designed around the "Fusion Core" concept, which orchestrates various decentralized services.

Fusion Core Orchestration

The tamv-fusion-core Edge Function serves as the system's "Heartbeat," monitoring health and synchronizing content.

Implementation Roadmap

The project follows a "Surgical Modular Plan" where features are implemented according to their priority and architectural dependency.

Phase	Module	Status	Core Technologies
1	QA Constitutional	✅ Active	ESLint, Custom Scripts, CI/CD
2	Social Core	⚠️ Progress	Realtime, Supabase RLS
3	Isabella Prime	✅ Active	LLM (Gemini), TTS (ElevenLabs)
4	DreamSpaces	✅ Active	Three.js, React Three Fiber
5	Economy / TAU	✅ Active	Stripe, Ledger, TAU tokens

Sources: PLAN-TAMV-MODULAR.md:20-50, README_TAMV_COMPLETO.md:100-140

Summary

The TAMV Architecture Overview describes a system where structural integrity is paramount. By enforcing strict isolation between navigation and feature modules and using automated "Constitutional" checks, the system ensures a deterministic and scalable environment. This structure supports advanced features like the Isabella AI and DreamSpaces XR environments while maintaining a secure and audit-ready foundation through the Fusion Core and MSR Registry.