# no-country-simulation/g10-brasil-equipo-26 architecture

> Architecture diagram of the GitHub repository no-country-simulation/g10-brasil-equipo-26, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/no-country-simulation/g10-brasil-equipo-26
- Repository: https://github.com/no-country-simulation/g10-brasil-equipo-26

## Overview

MentorIA Tech turns a technical PDF, Markdown, or text document into source-grounded study material personalized by learner profile, format, and depth. The Streamlit interface submits a request to the FastAPI generation endpoint; the backend extracts pages, retrieves relevant passages, generates and validates structured content, then persists results. The product also supports document suitability checks, quiz practice, and optional OCI storage. Edges follow README-described flow and SOURCE INDEX references; unsampled implementation details are omitted where relationships cannot be verified.

Main entry points: [`rag/main.py`](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/main.py) (FastAPI service), [`app/main.py`](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/main.py) (Streamlit app), [`rag/pipeline/llm_pipeline.py`](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/llm_pipeline.py) (LLM generation), [`rag/persistencia.py`](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/persistencia.py) (Persistence facade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_streamlit["Streamlit app<br/>[main.py]"]
  node_identity["User identity<br/>[identidade.py]"]
  node_api_client["HTTP client<br/>[api_client.py]"]
  node_quiz_ui["Quiz interface<br/>[quiz_ui.py]"]
  node_renderers["Content renderers<br/>[renderizadores.py]"]
end

subgraph group_api["Generation API"]
  node_fastapi["FastAPI service<br/>[main.py]"]
  node_ingestion["Document extraction<br/>[ingestao.py]"]
end

subgraph group_rag["RAG and generation"]
  node_contracts["Data contracts<br/>[schemas.py]"]
  node_retrieval["RAG retrieval<br/>[rag_retrieval.py]"]
  node_generation["LLM generation<br/>[llm_pipeline.py]"]
  node_suitability["Document suitability"]
end

subgraph group_state["Persistence and telemetry"]
  node_sqlite[("SQLite store<br/>[database.py]")]
  node_persistence["Persistence facade<br/>[persistencia.py]"]
  node_telemetry["LLM telemetry<br/>[telemetria_llm.py]"]
end

subgraph group_cloud["Cloud artifacts"]
  node_oci_bridge["OCI bridge<br/>[oci_bridge.py]"]
  node_oci_storage["OCI artifact storage<br/>[oci_storage.py]"]
end

node_learner(("Learner"))
node_external_llms{{"Gemini and Groq"}}
node_oci[("OCI Object Storage")]

node_learner -->|"submits document"| node_streamlit
node_streamlit -->|"identifies user"| node_identity
node_streamlit -->|"requests generation"| node_api_client
node_api_client -->|"posts generation"| node_fastapi
node_fastapi -->|"extracts document"| node_ingestion
node_fastapi -->|"validates request"| node_contracts
node_fastapi -->|"requests context"| node_retrieval
node_retrieval -->|"embeds and ranks"| node_external_llms
node_fastapi -->|"generates content"| node_generation
node_generation -->|"calls with fallback"| node_external_llms
node_generation -->|"validates output"| node_contracts
node_fastapi -->|"assesses document"| node_suitability
node_suitability -->|"uses model keys"| node_generation
node_fastapi -->|"records generation"| node_persistence
node_persistence -->|"writes records"| node_sqlite
node_generation -->|"records calls"| node_telemetry
node_retrieval -->|"records calls"| node_telemetry
node_telemetry -->|"registers metrics"| node_persistence
node_persistence -->|"stores telemetry"| node_sqlite
node_fastapi -->|"returns result"| node_api_client
node_streamlit -->|"displays material"| node_renderers
node_streamlit -->|"supports quiz practice"| node_quiz_ui
node_quiz_ui -->|"requests quiz data"| node_api_client
node_renderers -->|"requests storage"| node_oci_bridge
node_oci_bridge -->|"uploads artifact"| node_oci_storage
node_oci_storage -->|"writes JSON"| node_oci

click node_streamlit "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/main.py"
click node_identity "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/identidade.py"
click node_api_client "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/api_client.py"
click node_quiz_ui "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/quiz_ui.py"
click node_renderers "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/renderizadores.py"
click node_fastapi "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/main.py"
click node_ingestion "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/backend/app/ingestao.py"
click node_contracts "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/schemas.py"
click node_retrieval "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/rag_retrieval.py"
click node_generation "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/llm_pipeline.py"
click node_suitability "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/avaliacao_documento.py"
click node_sqlite "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/database.py"
click node_persistence "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/persistencia.py"
click node_telemetry "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/telemetria_llm.py"
click node_oci_bridge "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/oci_bridge.py"
click node_oci_storage "https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/services/oci_storage.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_streamlit,node_identity,node_api_client,node_quiz_ui,node_renderers toneBlue
class node_fastapi,node_ingestion,node_oci toneAmber
class node_contracts,node_retrieval,node_generation,node_suitability toneMint
class node_sqlite,node_persistence,node_telemetry toneRose
class node_oci_bridge,node_oci_storage,node_learner,node_external_llms toneIndigo
```

## Components

### Learner experience

- [Streamlit app](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/main.py): `app/main.py`
- [User identity](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/identidade.py): `app/identidade.py`
- [HTTP client](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/api_client.py): `app/api_client.py`
- [Quiz interface](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/quiz_ui.py): `app/quiz_ui.py`
- [Content renderers](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/renderizadores.py): `app/renderizadores.py`

### Generation API

- [FastAPI service](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/main.py): `rag/main.py`
- [Document extraction](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/backend/app/ingestao.py): `backend/app/ingestao.py`

### RAG and generation

- [Data contracts](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/schemas.py): `rag/pipeline/schemas.py`
- [RAG retrieval](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/rag_retrieval.py): `rag/pipeline/rag_retrieval.py`
- [LLM generation](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/llm_pipeline.py): `rag/pipeline/llm_pipeline.py`
- [Document suitability](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/avaliacao_documento.py): `rag/pipeline/avaliacao_documento.py`

### Persistence and telemetry

- [SQLite store](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/database.py): `rag/database.py`
- [Persistence facade](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/persistencia.py): `rag/persistencia.py`
- [LLM telemetry](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/rag/pipeline/telemetria_llm.py): `rag/pipeline/telemetria_llm.py`

### Cloud artifacts

- [OCI bridge](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/app/oci_bridge.py): `app/oci_bridge.py`
- [OCI artifact storage](https://github.com/no-country-simulation/g10-brasil-equipo-26/blob/main/services/oci_storage.py): `services/oci_storage.py`

### Other components

- **Learner**
- **Gemini and Groq**
- **OCI Object Storage**

## Connections

- Learner → Streamlit app: submits document (evidence: `README.md`)
- Streamlit app → User identity: identifies user (evidence: `app/main.py`)
- Streamlit app → HTTP client: requests generation (evidence: `app/main.py`)
- HTTP client → FastAPI service: posts generation (evidence: `app/api_client.py`)
- FastAPI service → Document extraction: extracts document (evidence: `rag/main.py`)
- FastAPI service → Data contracts: validates request (evidence: `rag/main.py`)
- FastAPI service → RAG retrieval: requests context (evidence: `rag/main.py`)
- RAG retrieval → Gemini and Groq: embeds and ranks (evidence: `README.md`)
- FastAPI service → LLM generation: generates content (evidence: `rag/main.py`)
- LLM generation → Gemini and Groq: calls with fallback (evidence: `README.md`)
- LLM generation → Data contracts: validates output (evidence: `rag/pipeline/llm_pipeline.py`)
- FastAPI service → Document suitability: assesses document (evidence: `rag/main.py`)
- Document suitability → LLM generation: uses model keys (evidence: `rag/pipeline/avaliacao_documento.py`)
- FastAPI service → Persistence facade: records generation (evidence: `rag/main.py`)
- Persistence facade → SQLite store: writes records (evidence: `rag/persistencia.py`)
- LLM generation → LLM telemetry: records calls (evidence: `rag/pipeline/llm_pipeline.py`)
- RAG retrieval → LLM telemetry: records calls (evidence: `rag/pipeline/rag_retrieval.py`)
- LLM telemetry → Persistence facade: registers metrics (evidence: `rag/pipeline/telemetria_llm.py`)
- Persistence facade → SQLite store: stores telemetry (evidence: `rag/persistencia.py`)
- FastAPI service → HTTP client: returns result (evidence: `README.md`)
- Streamlit app → Content renderers: displays material (evidence: `app/main.py`)
- Streamlit app → Quiz interface: supports quiz practice (evidence: `app/main.py`)
- Quiz interface → HTTP client: requests quiz data (evidence: `app/quiz_ui.py`)
- Content renderers → OCI bridge: requests storage (evidence: `app/renderizadores.py`)
- OCI bridge → OCI artifact storage: uploads artifact (evidence: `app/oci_bridge.py`)
- OCI artifact storage → OCI Object Storage: writes JSON (evidence: `README.md`)
