React Frontend Architecture

Relevant source files

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

• frontend/frontend-app/package.json
• frontend/frontend-app/README.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-FRONTEND-BACKEND-COMPLETO.md
• TAMV-MASTER-DOCUMENTATION.md

Introduction

The React Frontend Architecture for the Territorio Autónomo de Memoria Viva (TAMV) project is designed as a professional-grade, high-performance ecosystem integrating 2D, 3D, and Extended Reality (XR) experiences. Built with a focus on "Zero Mediocrity," the architecture leverages a modern technical stack centered around React 19, TypeScript, and Vite to deliver fluid animations and immersive digital sovereignty tools.

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md, TAMV-MASTER-DOCUMENTATION.md:95-103, frontend/frontend-app/package.json:20-22

The system follows a modular architecture that separates 2D UI components from 3D/XR engine logic. It is structured to handle real-time social interactions, ethical AI visualization through the Isabella framework, and secure blockchain integration for digital assets and NFT marketplaces.

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:14-30, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:180-210

Core Technical Stack

The frontend utilizes a "Hardened Stack" to ensure high frame rates (60+ FPS) and strict type safety.

UI & State Management

• React 19 & TypeScript: Core UI library and type-safe development environment.
• Zustand: Lightweight global state management for handling user sessions and app state.
• TanStack Query (React Query): Used for server state management, caching, and optimistic updates.
• React Router DOM: Handles client-side navigation and protected routes.

Sources: frontend/frontend-app/package.json:17-25, ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md:46-56

Visuals & Styling

• Tailwind CSS: Utility-first styling for consistent UI design.
• Framer Motion: Powering fluid 2D animations and micro-interactions.
• Radix UI & Lucide React: Provides accessible UI primitives and a modern icon set.

Sources: frontend/frontend-app/package.json:21-23, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:19-25

Immersive Engines (3D/XR)

• Three.js & React Three Fiber (R3F): The foundation for WebGL rendering and 3D scenes.
• WebXR APIs: Native support for VR and AR experiences (e.g., Meta Quest, Apple Vision Pro).
• Rapier: Real-time physics engine for 3D interactions.

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:32-45, TAMV-MASTER-DOCUMENTATION.md:104-106

Architectural Components

The architecture is divided into logical layers to facilitate scalability and the "DreamSpaces" engine integration.

Component Hierarchy

The project uses a structured directory for 2D, 3D, and XR components:

Category	Description	Key Technologies
2D UI	Standard web interfaces, forms, and social feeds.	Tailwind, Radix UI
3D Scenes	Landing pages with interactive logo and particle systems.	R3F, Drei
XR/VR	Immersive environments with hand tracking and spatial audio.	@react-three/xr
4D/Temporal	Time-based visualizations and causal connection graphs.	GSAP, Custom Shaders

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:310-345

Data Flow Diagram

The following diagram illustrates how the frontend interacts with the backend services and manages local state.

The frontend architecture ensures that data fetching is decoupled from UI rendering, allowing for optimistic updates and smooth loading states.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:180-210, ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md:58-65

Key Features & Hooks

The implementation utilizes custom React hooks to manage complex logic for authentication, pagination, and blockchain interactions.

1. Authentication Flow

The useAuth hook manages the user's lifecycle, including token verification and secure session persistence using JWT.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:215-240

2. Social Feed & Interaction

Supports infinite scroll and paginated data fetching for posts, comments, and likes.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:245-275

3. Wallet & Web3 Integration

The useWallet hook leverages wagmi and ethers to connect to decentralized wallets like MetaMask for NFT marketplace interactions.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:280-295

User Authentication Sequence

This diagram shows the sequence of a login request through the frontend architecture.

The authentication process emphasizes secure token storage and immediate state synchronization.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:225-240, ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md:135-140

Performance & Design Principles

The TAMV frontend adheres to strict performance metrics to maintain high-quality visual experiences.

Target Metrics

• Frame Rate: 60 FPS constant for 2D/3D; 90+ FPS for VR (Meta Quest).
• Web Vitals: LCP < 2.5s, FID < 100ms.
• Asset Optimization: Use of Draco compression for 3D models and Basis Universal for textures.

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:175-185, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:225-240

Design Language (Glassmorphism)

The UI implements a "Glassmorphism" design language, characterized by:

• Background Blurs: 20px blur with semi-transparent backgrounds (rgba(20, 20, 20, 0.7)).
• Dark Mode: A deep black primary palette (#0A0A0A) with vibrant accent colors like Azure (#3B82F6).

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:85-115, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-FRONTEND-BACKEND-COMPLETO.md:30-45

Summary

The TAMV React Frontend Architecture provides a robust foundation for a decentralized, immersive social ecosystem. By combining cutting-edge libraries like React 19 and Three.js with a modular component structure and specialized hooks for Auth and Web3, the system achieves a "Production Ready" state capable of delivering AAA-quality visual experiences across web and XR platforms.

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/RESUMEN-FINAL-SESION.md:10-15, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-VISUAL-EXPERIENCE-SPEC.md:380-385