---
sidebar_position: 1
title: "Visão Geral do Letramento"
---

O sistema de letramento digital é uma parte independente da plataforma, responsável por atividades que não usam Blockly nem interpretador. As atividades são arquivos HTML autocontidos executados em iframe sandbox.

## Arquitetura do sistema

```mermaid
graph TD
    REG["letramentoRegistry.js
catálogo de atividades"] --> FRAME["AtividadeRuntimeFrame
container React + iframe"]
    FRAME --> HTML["Atividade HTML
index.html + activity.js"]
    HTML -- "postMessage" --> FRAME
    FRAME --> BUS["letramentoEventBus
eventos internos"]
    BUS --> CTX["LetramentoStateContext
estado de execução"]
    CTX --> STORE["letramentoStorage.js
persistência localStorage"]
```

## Como funciona ponta a ponta

```mermaid
sequenceDiagram
    participant U as Usuário
    participant R as React (página)
    participant F as AtividadeRuntimeFrame
    participant I as Iframe (index.html)
    participant B as letramentoEventBus
    participant C as LetramentoStateContext
    participant S as letramentoStorage

    U->>R: Abre uma atividade
    R->>F: Carrega atividade pelo registro
    F->>I: Renderiza iframe sandbox
    I->>F: postMessage(type: started)
    F->>B: emit atividade:started
    B->>C: estado RUNNING

    U->>I: Interage e resolve a atividade
    I->>F: postMessage(type: success, score)
    F->>B: emit atividade:success
    B->>C: atualiza progresso da trilha
    C->>S: persiste no localStorage
    S-->>R: progresso disponível para próximas sessões
```

## Capacidades do letramento

O módulo de letramento foi desenhado para funcionar como um runtime desacoplado com características de plataforma educacional:

- Catálogo de atividades por categoria e trilha.
- Execução isolada por iframe, sem acoplamento direto com React.
- Contrato de eventos para início, progresso e conclusão.
- Rastreamento de progresso e persistência local.
- Reentrada em sessão posterior com estado salvo.

## Relação com o padrão LMS

O desenho é inspirado no modelo de Learning Management Systems (LMS), com foco em trilha de conteúdo, execução de atividade e acompanhamento de resultado.

```mermaid
graph LR
    LMS[Modelo LMS] --> CAT[Catálogo de conteúdo]
    LMS --> RUN[Runtime da atividade]
    LMS --> TRK[Rastreamento de progresso]
    LMS --> REP[Resultado de aprendizagem]

    CAT --> REG[letramentoRegistry.js]
    RUN --> IFM[AtividadeRuntimeFrame + iframe]
    TRK --> CTX[LetramentoStateContext]
    REP --> STO[letramentoStorage.js]
```

Este módulo não implementa um LMS completo (como gestão de turmas, avaliação institucional, relatórios administrativos e papéis avançados), mas aplica os blocos essenciais de experiência de aprendizagem orientada por atividade.

## Componentes principais

| Arquivo | Responsabilidade |
|---|---|
| `letramentoRegistry.js` | Cataloga todas as atividades de letramento |
| `AtividadeRuntimeFrame.jsx` | Monta o iframe e faz a ponte com React |
| `letramentoEvents.js` | Event bus para comunicação desacoplada |
| `LetramentoStateContext.jsx` | Estado global de execução do letramento |
| `letramentoStorage.js` | Persistência de progresso no `localStorage` |

## Organização das atividades

```mermaid
graph TD
    LT["atividades/letramento/"] --> C1["categoria-1/"]
    LT --> C2["categoria-2/"]
    C1 --> A1["nome-atividade/
index.html + activity.js"]
    C1 --> A2["outra-atividade/
index.html + activity.js"]
```

As atividades são agrupadas por categoria dentro de `app/src/atividades/letramento/`.

## Próximas páginas

- `contrato-postmessage`: como a atividade HTML se comunica com React.
- `como-adicionar`: passo a passo para criar uma nova atividade de letramento.
- `modelo-lms`: visão arquitetural do padrão LMS aplicado ao letramento.
