fix: persist progress in writable path on hugging face spaces

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [Unreleased]
+### Added
+- Estrutura de documentação (`architecture`, `contributing`, `llms.txt`)
+
+## [2026-03-06]
+### Added
+- Sidebar com filtros por status e disciplina
+- Toggle de métricas (`Filtro`/`Global`)
+- Deploy em Hugging Face Space (Docker)
+
+### Changed
+- Compatibilidade UI: `segmented_control` substituído por `radio`
+
+### Fixed
+- Configuração do Docker Space alinhada à documentação oficial HF

README.md

@@ -10,29 +10,58 @@ pinned: false
 
 # 🎖️ PMDF – CFO 2025 | Dashboard de Estudos
 
-## Como rodar
+Dashboard em Streamlit para acompanhar progresso por disciplina e tópico do edital PMDF CFO 2025.
+
+## Quick Start
 
 ### Com `uv` (recomendado)
 
 ```bash
-# 1. Crie o ambiente virtual e instale as dependências
 uv sync
-
-# 2. Rode o app
 uv run streamlit run app.py
 ```
 
-### Alternativa sem uv
+### Alternativa sem `uv`
+
 ```bash
-pip install streamlit
+pip install -r requirements.txt
 streamlit run app.py
 ```
 
-## Funcionalidades
+## Features
+
+- Controle de estudo por checkbox em cada tópico
+- Filtro por status (`Todas`, `Pendentes`, `Concluídas`)
+- Filtro por disciplina na sidebar
+- Métricas no topo em modo `Filtro` ou `Global`
+- Persistência local automática em `progress.json`
+
+## Configuração
+
+| Variável/Arquivo | Descrição | Padrão |
+|---|---|---|
+| `PROGRESS_FILE` (`app.py`) | Arquivo de persistência | `progress.json` |
+| `PORT` (Docker/Space) | Porta do Streamlit | `7860` |
+
+## Documentação
+
+- [Arquitetura](./docs/architecture.md)
+- [Contribuição](./docs/contributing.md)
+- [Changelog](./CHANGELOG.md)
+- [Plano de UI (Mermaid)](./docs/plans/2026-03-06-sidebar-filtros-design.md)
+
+## API Reference
+
+Este projeto não expõe API HTTP pública; toda a interação ocorre na interface Streamlit.
+
+## Contribuindo
+
+1. Crie branch a partir de `main`
+2. Rode `uv run --no-project python -m py_compile app.py`
+3. Abra PR com descrição, validação e screenshots quando houver mudança visual
+
+Detalhes completos em [docs/contributing.md](./docs/contributing.md).
+
+## License
 
-- ✅ Checkbox por tópico — marque o que já estudou
-- 📊 Barra de progresso por disciplina (sidebar + card)
-- 📈 Progresso geral do edital em tempo real
-- 💾 Persistência automática em `progress.json`
-- 🗑️ Botão para resetar tudo
-- 🎨 Cor distinta por disciplina
+Uso educacional/pessoal. Defina licença formal antes de distribuição comercial.

app.py

@@ -1,8 +1,33 @@
 import streamlit as st
 import json
+import os
 from pathlib import Path
 
-PROGRESS_FILE = Path("progress.json")
+
+def resolve_progress_file():
+    env_path = os.getenv("PROGRESS_FILE")
+    candidates = []
+    if env_path:
+        candidates.append(Path(env_path))
+    candidates.extend([
+        Path("/data/progress.json"),
+        Path("progress.json"),
+        Path("/tmp/progress.json"),
+    ])
+
+    for candidate in candidates:
+        try:
+            candidate.parent.mkdir(parents=True, exist_ok=True)
+            with open(candidate, "a", encoding="utf-8"):
+                pass
+            return candidate
+        except OSError:
+            continue
+
+    return Path("/tmp/progress.json")
+
+
+PROGRESS_FILE = resolve_progress_file()
 
 EDITAL = {
     "Língua Portuguesa": [
@@ -326,13 +351,13 @@ DISC_COLORS = {
 
 def load_progress():
     if PROGRESS_FILE.exists():
-        with open(PROGRESS_FILE, "r") as f:
+        with open(PROGRESS_FILE, "r", encoding="utf-8") as f:
             return json.load(f)
     return {}
 
 
 def save_progress(progress):
-    with open(PROGRESS_FILE, "w") as f:
+    with open(PROGRESS_FILE, "w", encoding="utf-8") as f:
         json.dump(progress, f, ensure_ascii=False, indent=2)
 
 

docs/architecture.md

@@ -0,0 +1,25 @@
+# Arquitetura
+
+## Visão Geral
+
+Aplicação monolítica em Streamlit (`app.py`) com estado em memória de sessão e persistência em JSON local.
+
+## Componentes
+
+- `app.py`: UI, regras de filtro, métricas e escrita de progresso.
+- `progress.json`: armazenamento local de marcações do usuário.
+- `Dockerfile`: execução no Hugging Face Spaces (SDK Docker).
+- `requirements.txt`: dependências mínimas para runtime.
+
+## Fluxo de Dados
+
+1. App inicia e carrega `progress.json`.
+2. Usuário interage com filtros/checkboxes.
+3. Estado em `st.session_state` é atualizado.
+4. Alterações são salvas em `progress.json`.
+5. Interface renderiza grupos/tópicos conforme filtros ativos.
+
+## Decisões
+
+- UI guiada por estado único (`ui_status_filter`, `ui_selected_discipline`, `ui_metrics_mode`).
+- Deploy em HF via Docker para compatibilidade estável.

docs/contributing.md

@@ -0,0 +1,29 @@
+# Contribuição
+
+## Pré-requisitos
+
+- Python 3.11+
+- `uv` instalado (preferencial)
+
+## Fluxo recomendado
+
+```bash
+git checkout -b feat/minha-mudanca
+uv sync
+uv run --no-project python -m py_compile app.py
+```
+
+## Padrões
+
+- Python com 4 espaços de indentação
+- `snake_case` para funções/variáveis
+- Constantes em `UPPER_CASE`
+
+## Pull Request
+
+Inclua sempre:
+
+- Objetivo da mudança
+- Como validar localmente
+- Screenshot/GIF em mudanças visuais
+- Impactos em deploy (se houver)

llms.txt

@@ -0,0 +1,13 @@
+# PMDF CFO Dashboard
+> Dashboard Streamlit para acompanhamento de estudos do edital PMDF CFO 2025.
+
+## Core Files
+- `app.py`: aplicação principal (UI, filtros, métricas, persistência)
+- `requirements.txt`: dependências de runtime
+- `Dockerfile`: execução no Hugging Face Spaces
+- `docs/`: documentação técnica e de contribuição
+
+## Key Concepts
+- Estado único de UI: filtros e métricas são derivados de `st.session_state`
+- Persistência local: progresso salvo em `progress.json`
+- Deploy Docker: Space usa `sdk: docker` e `app_port: 7860`