Frontend Architecture & QC Rules
Relevant source files
The following files were used as context for generating this wiki page:
The Frontend Architecture of the TAMV project is governed by the QC-TAMV-01 Constitutional Quality Framework. This framework defines non-negotiable technical invariants that translate architectural principles into executable mechanisms, such as linting, automated testing, and static analysis. It ensures structural determinism and total traceability across the civilizatory client.
The primary objective of these rules is to maintain a finite, predictable, and inspectable architecture where every technical artifact has a clear purpose and version. This governance is automated via the MD-X5 (Deca-V) pipeline, ensuring that rules are enforced by tools rather than human convention alone.
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:14-25, src/pages/wiki/implementacion/CicdPipelines.tsx:42-50
1. Constitutional Laws (L1–L9)
The core architecture is protected by nine constitutional laws (L1–L9). These laws enforce isolation between layers and restrict critical initializations to specific files.
| Law | Name | Technical Invariant |
|---|---|---|
| L1 | Single Root | createRoot must exist exclusively in src/main.tsx. |
| L2 | Single Router | BrowserRouter (or equivalent) is restricted to src/App.tsx. |
| L3 | Single Layout | Layout.tsx is mounted exactly once within App.tsx. |
| L4 | Route-Page Map | Every file in src/pages/* must correspond to a single route. |
| L5 | Page Responsibility | Pages compose modules and domains; they must not initialize services. |
| L6 | Independent Modules | src/modules/* cannot import react-router-dom or files from src/pages. |
| L7 | Visual Isolation | The root path / cannot display components exclusive to sub-routes (e.g., /login). |
| L8 | SOC | Separation of Concerns: No layer assumes the responsibilities of another. |
| L9 | Audited Exceptions | Any violation of L1-L8 requires a formal registry in DigyTAMV. |
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:28-40, federation/tamv-digital-nexus/scripts/check-architecture.ts:116-240
2. Automated Architecture Validation
The system utilizes a custom validation script, check-architecture.ts, to programmatically detect violations of the constitutional laws. This script analyzes the project's dependency graph by categorizing files into specific types and inspecting their imports.
File Categorization Logic
The script classifies source files based on their directory structure:
- Page: Located in
src/pages. - Module: Located in
src/modules. - Domain: Located in
src/domains. - Core: Located in
src/core. - Integration: Located in
src/integrations.
Sources: federation/tamv-digital-nexus/scripts/check-architecture.ts:31-41, federation/tamv-digital-nexus/scripts/check-architecture.ts:84-95
Validation Flow
The validator extracts ES6 and dynamic imports using regex patterns to verify architectural boundaries.
The script specifically looks for imports of react-router-dom within modules (L6 violation) and createRoot calls outside of the main entry point (L1 violation).
Sources: federation/tamv-digital-nexus/scripts/check-architecture.ts:116-240, federation/tamv-digital-nexus/scripts/check-architecture.ts:285-300
3. MD-X5 (Deca-V) Pipeline
The MD-X5 Pipeline defines ten mandatory cycles that must be completed for any Pull Request to be merged into main or release/*. This ensures that technical excellence and constitutional compliance are verified before deployment.
Pipeline Cycles
- lint: ESLint execution with
eslint-plugin-tamvin error mode. - typecheck: TypeScript validation without emission (
tsc --noEmit). - test: Unit testing via Vitest.
- test:e2e: Integration testing via Playwright.
- contract-test: Verification of contracts between federated modules.
- security-scan: Security gates enforced by DEKATEOTL.
- sbom/check-licenses: Analysis of Software Bill of Materials and licensing.
- build + artifact signing: Production build and cryptographic signing.
- deploy canary: Gradual deployment to a canary environment.
- post-deploy verification: Automatic verification and potential rollback.
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:53-65
4. Frontend Component & Routing Structure
The application's entry point, App.tsx, serves as the implementation site for L2 (Single Router). It centralizes the BrowserRouter and maps internal routes to specific page components.
Routing Mechanism
The routing system differentiates between static routes and a dynamic wiki system. The dynamic wiki uses import.meta.glob to discover and slugify page components from the filesystem automatically.
| Component | Path Pattern | Responsibility |
|---|---|---|
Index | / | Main landing interface. |
ArticleRouter | /articulo/:slug | Canonical route for specific wiki articles. |
WikiPage | /wiki/:sectionId/:slug | Dynamic rendering of wiki modules and articles. |
AppShell | N/A | High-level layout including the navigation sidebar and header. |
Sources: src/App.tsx:56-78, src/App.tsx:238-275
Wiki Navigation Logic
The ArticleRouter determines the rendering target by matching the URL slug against a pre-indexed list of components derived from the project's folder structure. It provides navigation context, such as links to adjacent articles and module titles.
5. Technology Stack & Operational Status
The frontend is built on a modern reactive stack, currently reported at 90% operational readiness for the core layers.
- Runtime/Build: Node 20, TypeScript 5, Vite 5.
- Framework: React 18.
- Styling: Tailwind CSS.
- State/Data: Zustand, React Query.
- Visuals: Three.js/WebXR for XR Worlds (75% readiness).
Sources: src/pages/wiki/metaverso-xr/RoadmapCivilizatorio.tsx:75-85, src/pages/wiki/metaverso-xr/RoadmapCivilizatorio.tsx:105-115
Frontend Architecture & QC Rules within TAMV ensure that the user interface remains a strictly controlled, deterministic portal to the civilizatory system. By enforcing L1-L9 through the architecture script and the MD-X5 pipeline, the project guarantees that no code reaches production without meeting established sovereignty and quality standards.
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:105-115, src/pages/wiki/metaverso-xr/RoadmapCivilizatorio.tsx:205-215