# lucian094/mapaia architecture

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

- Interactive diagram: https://gitdiagram.com/lucian094/mapaia
- Repository: https://github.com/lucian094/mapaia

## Overview

MAPAIA is an interactive Spanish-language guide and methodology for adopting AI agents in software development. Its primary reader journey is to self-assess (or choose a profile), follow a tailored route through the metro map and articles, and track visited stations. The graph includes documented learning topics and the sampled content, routing, glossary, and persistence layers. Article rendering and UI wiring are only partly evidenced by the excerpts, so uncertain links are omitted.

Main entry points: [`src/content.config.ts`](https://github.com/lucian094/mapaia/blob/main/src/content.config.ts) (Markdown collection), [`astro.config.ts`](https://github.com/lucian094/mapaia/blob/main/astro.config.ts) (Markdown configuration), [`src/pages/[...slug].astro`](https://github.com/lucian094/mapaia/blob/main/src/pages/%5B...slug%5D.astro) (Article rendering), [`02-pathing/autoevaluacion.md`](https://github.com/lucian094/mapaia/blob/main/02-pathing/autoevaluacion.md) (Self-assessment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_journey["Reader journey"]
  node_self_assessment["Self-assessment<br/>[autoevaluacion.md]"]
  node_quiz_data["Quiz and scoring<br/>[quiz.ts]"]
  node_profile_state["Profile state<br/>[perfil.ts]"]
  node_route_data["Personalized routes<br/>[mapa.ts]"]
  node_progress_state["Visit progress<br/>[progreso.ts]"]
end

subgraph group_content["Learning content"]
  node_foundations["Agent foundations"]
  node_profile_guides["Profile guides"]
  node_practice["Agent practice"]
  node_extensions["Extensibility"]
end

subgraph group_site["Site presentation"]
  node_article_rendering["Article rendering<br/>[&#91;...slug&#93;.astro]"]
  node_layouts["Page layouts"]
  node_metro_map["Metro map UI<br/>[MapaMetro.astro]"]
  node_home["Home page<br/>[index.astro]"]
  node_test_page["Test page<br/>[test.astro]"]
  node_glossary_page["Glossary page<br/>[glosario.astro]"]
end

subgraph group_runtime["Content processing"]
  node_content_collection["Markdown collection<br/>[content.config.ts]"]
  node_glossary_data["Glossary parsing<br/>[glosario.ts]"]
  node_glossary_match["Term detection"]
  node_glossary_plugin["Glossary plugin<br/>[remark-glosario.ts]"]
  node_link_plugin["Markdown links<br/>[remark-links-md.ts]"]
  node_link_rewrite["Link rewriting<br/>[links-md.ts]"]
  node_astro_config["Markdown configuration<br/>[astro.config.ts]"]
end

node_reader(("Reader"))

node_reader -->|"answers questions"| node_self_assessment
node_self_assessment -->|"opens test"| node_test_page
node_test_page -.->|"uses questions"| node_quiz_data
node_quiz_data -->|"derives profile"| node_profile_state
node_reader -->|"chooses route"| node_metro_map
node_home -.->|"presents routes"| node_route_data
node_route_data -->|"uses profile type"| node_profile_state
node_reader -->|"reads articles"| node_article_rendering
node_article_rendering -.->|"loads articles"| node_content_collection
node_article_rendering -.->|"renders with"| node_layouts
node_content_collection -->|"collects Markdown"| node_foundations
node_content_collection -->|"collects Markdown"| node_profile_guides
node_content_collection -->|"collects Markdown"| node_practice
node_content_collection -->|"collects Markdown"| node_extensions
node_reader -.->|"tracks visits"| node_progress_state
node_progress_state -->|"persists in browser"| node_reader
node_reader -->|"looks up terms"| node_glossary_page
node_astro_config -->|"loads glossary terms"| node_glossary_data
node_astro_config -->|"registers plugin"| node_glossary_plugin
node_astro_config -->|"registers plugin"| node_link_plugin
node_glossary_plugin -->|"segments text"| node_glossary_match
node_glossary_match -->|"normalizes terms"| node_glossary_data
node_link_plugin -->|"rewrites links"| node_link_rewrite

click node_self_assessment "https://github.com/lucian094/mapaia/blob/main/02-pathing/autoevaluacion.md"
click node_quiz_data "https://github.com/lucian094/mapaia/blob/main/src/data/quiz.ts"
click node_profile_state "https://github.com/lucian094/mapaia/blob/main/src/lib/perfil.ts"
click node_route_data "https://github.com/lucian094/mapaia/blob/main/src/data/mapa.ts"
click node_progress_state "https://github.com/lucian094/mapaia/blob/main/src/lib/progreso.ts"
click node_foundations "https://github.com/lucian094/mapaia/tree/main/01-fundamentos"
click node_profile_guides "https://github.com/lucian094/mapaia/tree/main/02-pathing"
click node_practice "https://github.com/lucian094/mapaia/tree/main/03-practica"
click node_extensions "https://github.com/lucian094/mapaia/tree/main/04-extensibilidad"
click node_content_collection "https://github.com/lucian094/mapaia/blob/main/src/content.config.ts"
click node_article_rendering "https://github.com/lucian094/mapaia/blob/main/src/pages/%5B...slug%5D.astro"
click node_layouts "https://github.com/lucian094/mapaia/tree/main/src/layouts"
click node_metro_map "https://github.com/lucian094/mapaia/blob/main/src/components/MapaMetro.astro"
click node_home "https://github.com/lucian094/mapaia/blob/main/src/pages/index.astro"
click node_test_page "https://github.com/lucian094/mapaia/blob/main/src/pages/test.astro"
click node_glossary_page "https://github.com/lucian094/mapaia/blob/main/src/pages/glosario.astro"
click node_glossary_data "https://github.com/lucian094/mapaia/blob/main/src/lib/glosario.ts"
click node_glossary_match "https://github.com/lucian094/mapaia/blob/main/src/lib/glosario-tooltip.ts"
click node_glossary_plugin "https://github.com/lucian094/mapaia/blob/main/src/lib/remark-glosario.ts"
click node_link_plugin "https://github.com/lucian094/mapaia/blob/main/src/lib/remark-links-md.ts"
click node_link_rewrite "https://github.com/lucian094/mapaia/blob/main/src/lib/links-md.ts"
click node_astro_config "https://github.com/lucian094/mapaia/blob/main/astro.config.ts"

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_self_assessment,node_quiz_data,node_profile_state,node_route_data,node_progress_state toneBlue
class node_foundations,node_profile_guides,node_practice,node_extensions toneAmber
class node_article_rendering,node_layouts,node_metro_map,node_home,node_test_page,node_glossary_page toneMint
class node_content_collection,node_glossary_data,node_glossary_match,node_glossary_plugin,node_link_plugin,node_link_rewrite,node_astro_config toneRose
class node_reader toneIndigo
```

## Components

### Reader journey

- [Self-assessment](https://github.com/lucian094/mapaia/blob/main/02-pathing/autoevaluacion.md): `02-pathing/autoevaluacion.md`
- [Quiz and scoring](https://github.com/lucian094/mapaia/blob/main/src/data/quiz.ts): `src/data/quiz.ts`
- [Profile state](https://github.com/lucian094/mapaia/blob/main/src/lib/perfil.ts): `src/lib/perfil.ts`
- [Personalized routes](https://github.com/lucian094/mapaia/blob/main/src/data/mapa.ts): `src/data/mapa.ts`
- [Visit progress](https://github.com/lucian094/mapaia/blob/main/src/lib/progreso.ts): `src/lib/progreso.ts`

### Learning content

- [Agent foundations](https://github.com/lucian094/mapaia/tree/main/01-fundamentos): `01-fundamentos`
- [Profile guides](https://github.com/lucian094/mapaia/tree/main/02-pathing): `02-pathing`
- [Agent practice](https://github.com/lucian094/mapaia/tree/main/03-practica): `03-practica`
- [Extensibility](https://github.com/lucian094/mapaia/tree/main/04-extensibilidad): `04-extensibilidad`

### Site presentation

- [Article rendering](https://github.com/lucian094/mapaia/blob/main/src/pages/%5B...slug%5D.astro): `src/pages/[...slug].astro`
- [Page layouts](https://github.com/lucian094/mapaia/tree/main/src/layouts): `src/layouts`
- [Metro map UI](https://github.com/lucian094/mapaia/blob/main/src/components/MapaMetro.astro): `src/components/MapaMetro.astro`
- [Home page](https://github.com/lucian094/mapaia/blob/main/src/pages/index.astro): `src/pages/index.astro`
- [Test page](https://github.com/lucian094/mapaia/blob/main/src/pages/test.astro): `src/pages/test.astro`
- [Glossary page](https://github.com/lucian094/mapaia/blob/main/src/pages/glosario.astro): `src/pages/glosario.astro`

### Content processing

- [Markdown collection](https://github.com/lucian094/mapaia/blob/main/src/content.config.ts): `src/content.config.ts`
- [Glossary parsing](https://github.com/lucian094/mapaia/blob/main/src/lib/glosario.ts): `src/lib/glosario.ts`
- [Term detection](https://github.com/lucian094/mapaia/blob/main/src/lib/glosario-tooltip.ts): `src/lib/glosario-tooltip.ts`
- [Glossary plugin](https://github.com/lucian094/mapaia/blob/main/src/lib/remark-glosario.ts): `src/lib/remark-glosario.ts`
- [Markdown links](https://github.com/lucian094/mapaia/blob/main/src/lib/remark-links-md.ts): `src/lib/remark-links-md.ts`
- [Link rewriting](https://github.com/lucian094/mapaia/blob/main/src/lib/links-md.ts): `src/lib/links-md.ts`
- [Markdown configuration](https://github.com/lucian094/mapaia/blob/main/astro.config.ts): `astro.config.ts`

### Other components

- **Reader**

## Connections

- Reader → Self-assessment: answers questions (evidence: `README.md`)
- Self-assessment → Test page: opens test (evidence: `README.md`)
- Test page → Quiz and scoring: uses questions
- Quiz and scoring → Profile state: derives profile (evidence: `src/data/quiz.ts`)
- Reader → Metro map UI: chooses route (evidence: `README.md`)
- Home page → Personalized routes: presents routes
- Personalized routes → Profile state: uses profile type (evidence: `src/data/mapa.ts`)
- Reader → Article rendering: reads articles (evidence: `README.md`)
- Article rendering → Markdown collection: loads articles
- Article rendering → Page layouts: renders with
- Markdown collection → Agent foundations: collects Markdown (evidence: `src/content.config.ts`)
- Markdown collection → Profile guides: collects Markdown (evidence: `src/content.config.ts`)
- Markdown collection → Agent practice: collects Markdown (evidence: `src/content.config.ts`)
- Markdown collection → Extensibility: collects Markdown (evidence: `src/content.config.ts`)
- Reader → Visit progress: tracks visits
- Visit progress → Reader: persists in browser (evidence: `src/lib/progreso.ts`)
- Reader → Glossary page: looks up terms (evidence: `README.md`)
- Markdown configuration → Glossary parsing: loads glossary terms (evidence: `astro.config.ts`)
- Markdown configuration → Glossary plugin: registers plugin (evidence: `astro.config.ts`)
- Markdown configuration → Markdown links: registers plugin (evidence: `astro.config.ts`)
- Glossary plugin → Term detection: segments text (evidence: `src/lib/remark-glosario.ts`)
- Term detection → Glossary parsing: normalizes terms (evidence: `src/lib/glosario-tooltip.ts`)
- Markdown links → Link rewriting: rewrites links (evidence: `src/lib/remark-links-md.ts`)
