API Contracts & OpenAPI Specs
Relevant source files
The following files were used as context for generating this wiki page:
- federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml
- federation/tamv-digital-nexus/supabase/functions/tamv-unified-api/index.ts
- src/pages/wiki/implementacion/ApiIsni.tsx
- federation/tamv-digital-nexus/apps/web/src/hooks/useUnifiedAPI.ts
- README.md
- src/pages/wiki/modulo-cero/Introduccion.tsx
The TAMV Unified API serves as the central communication backbone for the TAMV Digital Nexus, implementing a microservices architecture organized into three primary pipelines: Critical Operations (Pipeline A), Adaptive Intelligence (Pipeline B), and Control & Coordination (CCP). These contracts define the technical standards for identity, security, and economic transactions within the federated ecosystem.
The system utilizes an OpenAPI 3.1.0 specification ("Sovereign" version) to enforce consistency across diverse services, including Auth, Security, AI Generation, and Governance. These specifications ensure interoperability between the frontend Unified API Client Hook and backend Edge Functions.
Sources: federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml:1-35, README.md:12-25, src/pages/wiki/modulo-cero/Introduccion.tsx:61-65
Architectural Pipelines
The API is structured around functional pipelines that isolate critical infrastructure from experimental or coordination services.
Pipeline Breakdown
| Pipeline | Focus Area | Ports/Services | Key Responsibilities |
|---|---|---|---|
| Pipeline A | Critical Operations | 8001-8005 | Authentication (JWT+PQC), Quantum Security, Saga Transactions, Payments (Stripe/TAU) |
| Pipeline B | Adaptive Intelligence | 8101-8105 | AI Generation (EOCT™), Voice (TTS/STT), Vector Embeddings (pgvector RAG) |
| CCP | Control & Coordination | 8200-8202 | Orchestration, OPA-like Policy Engine, DAO Governance |
Sources: federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml:7-24
System Interaction Flow
The following diagram illustrates how a client interacts with the Unified API and how requests are routed to specific pipeline services.
Security and Authentication
TAMV implements a hybrid security model combining standard industry practices with post-quantum cryptography (PQC).
Security Schemes
The API supports two primary authentication mechanisms:
- BearerAuth: Standard JWT-based authentication.
- QuantumToken: JWT with post-quantum signatures utilizing the Dilithium3 algorithm.
Sources: federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml:47-60
Post-Quantum Cryptography (PQC) Integration
The Security Service (8002) provides endpoints for hybrid key generation and signing payloads with Dilithium algorithms to protect against future quantum computing threats.
Core API Modules and Endpoints
Identity (ISNI/ID-NVIDA)
The ISNI (Infraestructura Soberana de Nombres e Identidades) layer manages user profiles and "Dignity Scores." It integrates with academic identifiers like ORCID and DOI.
- GET /id/me: Retrieves the current user's identity data.
- GET /id/dignity: Retrieves reputation and trust metrics.
- GET /api/profiles/:id: Resolution of ISNI/DID profiles.
Sources: federation/tamv-digital-nexus/supabase/functions/tamv-unified-api/index.ts:40-52, src/pages/wiki/implementacion/ApiIsni.tsx:17-30
Economy and Transactions (TCEP)
The TCEP (TAMV Credit & Exchange Protocol) handles internal ledgers and transfers. It utilizes a Saga pattern for transaction consistency.
| Endpoint | Method | Purpose | Source |
|---|---|---|---|
/tx/create | POST | Create transaction using Saga pattern | tamv.v1.yaml:372 |
/economy/transfer | POST | Transfer TCEP credits between users | index.ts:107 |
/economy/wallet | GET | Check balance and wallet status | index.ts:101 |
/payments/create | POST | Create intent for Stripe or TAU Ledger | tamv.v1.yaml:433 |
Governance and DAO
Decentralized governance is facilitated through the Governance Service (8202), allowing users to propose and vote on constitutional or economic changes.
- POST /dao/proposals: Creates a new proposal with an evidence hash.
- POST /dao/vote: Casts a vote on an active proposal.
- GET /policy/evaluate: Verifies if an action complies with OPA-like policy rules.
Sources: federation/tamv-digital-nexus/supabase/functions/tamv-unified-api/index.ts:60-98, federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml:630-650
Implementation Details
Data Models (Schemas)
The API contracts define strict schemas for all data objects to maintain consistency across the federation.
# Transaction Schema Example
Transaction:
type: object
properties:
id: { type: string, format: uuid }
amount: { type: number, example: 100.50 }
currency: { type: string, enum: [USD, TAU, TCEP] }
status: { type: string, enum: [pending, confirmed, failed] }
evidence_hash: { type: string }
Sources: federation/tamv-digital-nexus/packages/contracts/openapi/tamv.v1.yaml:144-165
Implementation of the Unified API Hook
The frontend interacts with these contracts via the useUnifiedAPI hook, which abstracts the Supabase Edge Function calls.
// federation/tamv-digital-nexus/apps/web/src/hooks/useUnifiedAPI.ts
async function apiCall<T = any>(path: string, method: 'GET' | 'POST' = 'GET', body?: any): Promise<T> {
const { data: sessionData } = await supabase.auth.getSession();
const token = sessionData?.session?.access_token;
// ... headers and fetch logic
const res = await fetch(API_BASE + path, {
method,
headers,
...(method !== 'GET' && body ? { body: JSON.stringify(body) } : {}),
});
return await res.json();
}
Sources: federation/tamv-digital-nexus/apps/web/src/hooks/useUnifiedAPI.ts:13-33
Conclusion
The API Contracts and OpenAPI Specs represent the "Sovereign" foundation of the TAMV project. By enforcing strict schemas, quantum-secure authentication, and a structured multi-pipeline architecture, the system ensures that identity, economy, and governance can operate reliably across a federated network of services. The shift from static documentation to executable contracts allows the project to maintain high technical quality and compliance with civilizatory principles.
Sources: README.md:95-105, src/pages/wiki/modulo-cero/Introduccion.tsx:61-68