Local Setup & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Local setup and configuration for the TAMV Atlas project involve preparing a full-stack environment that supports the MD-X4/X5 kernel, identity modules, and federated repository management. The system is designed as a monorepo consisting of a Vite-powered React frontend and a Node.js API server that interacts with various decentralized identity (DID) and persistent identifier (PID) services.
The environment requires specific configuration of environment variables to enable connectivity with backend services and optional persistence layers like Supabase. Developers must adhere to the QC-TAMV-01 Constitutional quality standards, which dictate structural invariants and mandatory linting/testing cycles during the local development process.
Sources: README.md:3-13, src/pages/wiki/implementacion/CicdPipelines.tsx:16-21
Prerequisites and Tech Stack
The TAMV Atlas platform utilizes a modern JavaScript/TypeScript stack. Development requires Node.js (Version 20+) and specific package management tools to handle the monorepo structure.
Core Technologies
- Frontend: React 18, Vite 5, Tailwind CSS, TypeScript 5.
- Backend: Node.js (HTTP native + ESM), Express.
- Persistence: PostgreSQL 15, Supabase (Optional).
- Quantum/XR: Qiskit, Three.js, WebXR.
Sources: src/pages/wiki/metaverso-xr/RoadmapCivilizatorio.tsx:55-61, README.md:7-13
Local Development Execution
The project provides standard npm scripts for initializing the frontend and backend services. These must be executed from the root of the repository.
# Install dependencies
npm install
# Start Frontend Development Server
npm run dev
# Start Backend API Server
npm run api:start
Sources: README.md:126-140
Quality Control Gates (npm scripts)
Before submitting code, developers must pass the MD-X5 (Deca-V) pipeline cycles locally to ensure compliance with the "Constitutional" quality framework.
| Script | Purpose |
|---|---|
npm run lint | ESLint execution with eslint-plugin-tamv in error mode. |
npm run typecheck | TypeScript verification without emitting files. |
npm run test | Unit testing via Vitest. |
npm run test:e2e | Integration testing via Playwright. |
npm run build | Production artifact generation and signing. |
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:49-61, README.md:133-138
Environment Configuration
Configuration is managed via environment variables. The API server behavior changes dynamically based on the presence of these variables, particularly regarding persistence and external services.
Essential Variables
| Variable | Description |
|---|---|
VITE_TAMV_BACKEND_URL | URL of the TAMV API server for frontend consumption. |
SUPABASE_URL | Endpoint for the Supabase persistence layer. |
SUPABASE_SERVICE_ROLE_KEY | Administrative key for Supabase access. |
TAMV_ORCID | Identifier for the ORCID academic identity integration. |
TAMV_ZENODO_RECORD | Reference for Zenodo DOI records. |
TAMV_ISNI | Identifier for the International Standard Name Identifier. |
Sources: README.md:83-86, README.md:144-149
Operational Logic
If SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are not provided, the API remains functional but disables routes requiring persistence, returning a 503 Service Unavailable status for those specific endpoints.
Sources: README.md:83-86
Architecture and Data Flow
The local setup establishes a relationship between the React frontend and the Node API, which acts as a gateway to the Atlas Kernel and federated services.
System Flow Diagram
The following diagram illustrates how the local components interact with external identity and repository services:
The diagram shows the local architectural stack where the Frontend communicates with the Node API, which then manages repository fusion and identity modules.
Sources: README.md:65-80
Repository Federation Setup
The TAMV Atlas includes scripts for unifying external repositories from the OsoPanda1 GitHub profile. This process populates the federation/ directory using git subtree.
Federation Mechanism
- Discovery: The system scans GitHub for repositories belonging to the owner.
- Manifest Generation: A
federation-manifest.jsonis created, indexing repository metadata, file counts, and service definitions. - Importation: Selected repositories are imported via
subtree --squash.
Sources: README.md:17-21, public/federation-manifest.json:4-15
Workspace Management
For specific federated environments like tamv-digital-nexus, an AGENTS.md file defines local safety locks and allowed operations.
CANON_LOCK=TRUE: Prevents renaming of canonical TAMV modules.CODE_WRITE=RESTRICTED: Restricts direct changes to production logic without human review.
Sources: federation/tamv-digital-nexus/AGENTS.md:5-25
QC-TAMV-01 Constitutional Invariants
Local configuration must respect the structural "laws" defined in the constitutional framework to pass the automated linting checks.
| Law | Constraint |
|---|---|
| L1 (Unique Root) | createRoot must exist only in src/main.tsx. |
| L2 (Unique Router) | BrowserRouter is restricted to src/App.tsx. |
| L3 (Unique Layout) | Layout.tsx must be mounted exactly once in App.tsx. |
| L6 (Independence) | src/modules/* cannot import from react-router-dom or pages. |
Sources: src/pages/wiki/implementacion/CicdPipelines.tsx:23-38
Conclusion
Setting up the TAMV Atlas locally provides a functional environment for iterating on digital civilization infrastructure. Success relies on configuring the environment variables for identity services and adhering to the MD-X5 pipeline and QC-TAMV-01 structural invariants. Once configured, the system allows for local development of frontend modules, API endpoints, and federated repository unifications.
Sources: README.md:162-166, src/pages/wiki/implementacion/CicdPipelines.tsx:102-110