# maxnelsonlopez/maxocracia-cero architecture

> Architecture diagram of the GitHub repository maxnelsonlopez/maxocracia-cero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxnelsonlopez/maxocracia-cero
- Repository: https://github.com/maxnelsonlopez/maxocracia-cero

## Overview

Maxocracia-Cero is a community platform for recording contributions and needs in life-time terms, making agreements, and governing shared rules. Its principal workflow is a participant posting an offer or need, the community connecting them, and the resulting agreement being signed and followed up. The README also identifies VHV, Maxo, SDV, education, and participatory governance as major capabilities. The graph combines those documented capabilities with sampled frontend and Concilio relationships; unsampled Flask route wiring is not inferred.

Main entry points: [`frontend/app/contracts/[id]/ContractDetailsClient.tsx`](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/contracts/%5Bid%5D/ContractDetailsClient.tsx) (Agreement experience), [`plataforma_educativa/app/buscador_routes.py`](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/buscador_routes.py) (Search routes), [`app/vhv_calculator.py`](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/vhv_calculator.py) (Vital footprint calculator), [`maxocontracts/concilio/cycle.py`](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/cycle.py) (Concilio cycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_community["Community platform"]
  node_webapp["Community web app<br/>[page.tsx]"]
  node_matching["Offer and need matching<br/>[page.tsx]"]
  node_network["Community network<br/>[interchanges.py]"]
  node_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_economy["Life accounting"]
  node_vhv["Vital footprint calculator<br/>[vhv_calculator.py]"]
  node_maxo["Maxo accounting<br/>[maxo.py]"]
  node_sdv["Dignity floor<br/>[sdv_analyzer.py]"]
  node_households["Household care accounts<br/>[micromax.py]"]
end

subgraph group_agreements["Agreements and oracles"]
  node_contractui["Agreement experience"]
  node_legalview["Plain-language contract view"]
  node_negotiation["Oracle negotiation panel"]
  node_contractengine["Contract rules<br/>[contract.py]"]
  node_ternura["Care validation block<br/>[ternura.py]"]
end

subgraph group_governance["Community governance"]
  node_governanceui["Voting and delegation<br/>[page.tsx]"]
  node_concilio["Concilio cycle<br/>[cycle.py]"]
  node_canon["Shared canon<br/>[canon.py]"]
  node_memory["Canon memory<br/>[memoria.py]"]
  node_engines["LLM engines<br/>[engines.py]"]
end

subgraph group_education["Educational platform"]
  node_learning["Education learning API<br/>[api_routes.py]"]
  node_search["Educational search<br/>[buscador.py]"]
  node_searchroutes["Search routes<br/>[buscador_routes.py]"]
  node_scoring["Search reliability scoring<br/>[score_engine.py]"]
  node_edudb[("Education database<br/>[db.py]")]
end

node_participant(("Participant"))

node_participant -->|"uses"| node_webapp
node_participant -->|"posts needs"| node_matching
node_matching -->|"connects offers"| node_network
node_network -->|"records agreement"| node_contractui
node_contractui -->|"renders"| node_legalview
node_contractui -->|"opens negotiation"| node_negotiation
node_contractui -->|"submits check-ins"| node_api
node_api -->|"requests calculation"| node_vhv
node_participant -->|"records contribution"| node_vhv
node_vhv -->|"anchors unit"| node_maxo
node_participant -->|"checks minimums"| node_sdv
node_participant -->|"tracks care"| node_households
node_participant -->|"votes or delegates"| node_governanceui
node_concilio -->|"calls engines"| node_engines
node_concilio -->|"uses canon"| node_canon
node_canon -->|"uses memory"| node_memory
node_contractengine -.->|"applies care rules"| node_ternura
node_searchroutes -->|"runs search"| node_search
node_searchroutes -->|"requests score"| node_scoring
node_search -->|"uses scoring"| node_scoring
node_learning -->|"reads and writes"| node_edudb
node_searchroutes -->|"reads and writes"| node_edudb

click node_webapp "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/page.tsx"
click node_matching "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/matching/page.tsx"
click node_network "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/interchanges.py"
click node_api "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/lib/api.ts"
click node_vhv "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/vhv_calculator.py"
click node_maxo "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/maxo.py"
click node_sdv "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/sdv_analyzer.py"
click node_households "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/micromax.py"
click node_contractui "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/contracts/%5Bid%5D/ContractDetailsClient.tsx"
click node_legalview "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/contracts/%5Bid%5D/LegalContractView.tsx"
click node_negotiation "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/components/OracleNegotiationPanel.tsx"
click node_contractengine "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/core/contract.py"
click node_ternura "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/blocks/ternura.py"
click node_governanceui "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/votaciones/page.tsx"
click node_concilio "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/cycle.py"
click node_canon "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/canon.py"
click node_memory "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/memoria.py"
click node_engines "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/oracles/engines.py"
click node_learning "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/api_routes.py"
click node_search "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/buscador.py"
click node_searchroutes "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/buscador_routes.py"
click node_scoring "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/score_engine.py"
click node_edudb "https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_matching,node_network,node_api toneBlue
class node_vhv,node_maxo,node_sdv,node_households toneAmber
class node_contractui,node_legalview,node_negotiation,node_contractengine,node_ternura toneMint
class node_governanceui,node_concilio,node_canon,node_memory,node_engines toneRose
class node_learning,node_search,node_searchroutes,node_scoring,node_edudb,node_participant toneIndigo
```

## Components

### Community platform

- [Community web app](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Offer and need matching](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/matching/page.tsx): `frontend/app/matching/page.tsx`
- [Community network](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/interchanges.py): `app/interchanges.py`
- [Frontend API client](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/lib/api.ts): `frontend/app/lib/api.ts`

### Life accounting

- [Vital footprint calculator](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/vhv_calculator.py): `app/vhv_calculator.py`
- [Maxo accounting](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/maxo.py): `app/maxo.py`
- [Dignity floor](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/sdv_analyzer.py): `app/sdv_analyzer.py`
- [Household care accounts](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/app/micromax.py): `app/micromax.py`

### Agreements and oracles

- [Agreement experience](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/contracts/%5Bid%5D/ContractDetailsClient.tsx): `frontend/app/contracts/[id]/ContractDetailsClient.tsx`
- [Plain-language contract view](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/contracts/%5Bid%5D/LegalContractView.tsx): `frontend/app/contracts/[id]/LegalContractView.tsx`
- [Oracle negotiation panel](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/components/OracleNegotiationPanel.tsx): `frontend/app/components/OracleNegotiationPanel.tsx`
- [Contract rules](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/core/contract.py): `maxocontracts/core/contract.py`
- [Care validation block](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/blocks/ternura.py): `maxocontracts/blocks/ternura.py`

### Community governance

- [Voting and delegation](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/frontend/app/votaciones/page.tsx): `frontend/app/votaciones/page.tsx`
- [Concilio cycle](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/cycle.py): `maxocontracts/concilio/cycle.py`
- [Shared canon](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/canon.py): `maxocontracts/concilio/canon.py`
- [Canon memory](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/concilio/memoria.py): `maxocontracts/concilio/memoria.py`
- [LLM engines](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/maxocontracts/oracles/engines.py): `maxocontracts/oracles/engines.py`

### Educational platform

- [Education learning API](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/api_routes.py): `plataforma_educativa/app/api_routes.py`
- [Educational search](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/buscador.py): `plataforma_educativa/app/buscador.py`
- [Search routes](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/buscador_routes.py): `plataforma_educativa/app/buscador_routes.py`
- [Search reliability scoring](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/score_engine.py): `plataforma_educativa/app/score_engine.py`
- [Education database](https://github.com/maxnelsonlopez/maxocracia-cero/blob/main/plataforma_educativa/app/db.py): `plataforma_educativa/app/db.py`

### Other components

- **Participant**

## Connections

- Participant → Community web app: uses (evidence: `README.md`)
- Participant → Offer and need matching: posts needs (evidence: `README.md`)
- Offer and need matching → Community network: connects offers (evidence: `README.md`)
- Community network → Agreement experience: records agreement (evidence: `README.md`)
- Agreement experience → Plain-language contract view: renders (evidence: `frontend/app/contracts/[id]/ContractDetailsClient.tsx`)
- Agreement experience → Oracle negotiation panel: opens negotiation (evidence: `frontend/app/contracts/[id]/ContractDetailsClient.tsx`)
- Agreement experience → Frontend API client: submits check-ins (evidence: `frontend/app/contracts/[id]/ContractDetailsClient.tsx`)
- Frontend API client → Vital footprint calculator: requests calculation (evidence: `frontend/app/lib/api.ts`)
- Participant → Vital footprint calculator: records contribution (evidence: `README.md`)
- Vital footprint calculator → Maxo accounting: anchors unit (evidence: `README.md`)
- Participant → Dignity floor: checks minimums (evidence: `README.md`)
- Participant → Household care accounts: tracks care (evidence: `README.md`)
- Participant → Voting and delegation: votes or delegates (evidence: `README.md`)
- Concilio cycle → LLM engines: calls engines (evidence: `maxocontracts/concilio/cycle.py`)
- Concilio cycle → Shared canon: uses canon (evidence: `maxocontracts/concilio/cycle.py`)
- Shared canon → Canon memory: uses memory (evidence: `maxocontracts/concilio/canon.py`)
- Contract rules → Care validation block: applies care rules
- Search routes → Educational search: runs search (evidence: `plataforma_educativa/app/buscador_routes.py`)
- Search routes → Search reliability scoring: requests score (evidence: `plataforma_educativa/app/buscador_routes.py`)
- Educational search → Search reliability scoring: uses scoring (evidence: `plataforma_educativa/app/buscador.py`)
- Education learning API → Education database: reads and writes (evidence: `plataforma_educativa/app/api_routes.py`)
- Search routes → Education database: reads and writes (evidence: `plataforma_educativa/app/buscador_routes.py`)