Skip to content

Repository files navigation

Escola Inteligente

Sistema de gestão escolar enterprise-ready focado em ajudar cada aluno a atingir seu potencial máximo.

Combina operação acadêmica completa, personalização por habilidade, inclusão formal (PEI), bem-estar socioemocional, comunicação bidirecional família-escola e IA responsável com aprovação humana.

21 módulos · ~80 tabelas · 388 testes · 3 provedores de IA


Índice


Stack Tecnológica

Camada Tecnologias
Backend Python 3.12+ · FastAPI (async) · SQLAlchemy 2.0 (async) · Alembic · PostgreSQL 16 + pgvector
Auth JWT (python-jose) · bcrypt (passlib) · TOTP MFA (pyotp)
Frontend TypeScript · React Native · Expo ~52 · Expo Router · React Native Paper (MD3)
Data TanStack Query v5 · Axios (interceptors com refresh token) · React Hook Form + Zod
IA Anthropic SDK · OpenAI SDK · Google GenAI · Jinja2 (prompts)
Infra Docker Compose · pytest + httpx (testes contra PostgreSQL real) · ruff · mypy

Módulos do Sistema

Fase 1 — MVP (11 módulos)

Módulo Descrição
Tenant Organizações e escolas (multi-tenant)
Identity Auth JWT, contas, sessões, RBAC com escopo por escola/turma/disciplina
People Alunos, staff, responsáveis e vínculos familiares
Academic Anos letivos, turmas, disciplinas e matrículas
Teaching Grade horária, aulas reais instanciadas e frequência por aula
Assessment Avaliações com rubricas, notas por critério e boletim
Inclusion Condições especiais, acomodações e PEI estruturado com workflow
Personalization Habilidades hierárquicas, evidências, mastery e intervenções com medição de impacto
Competitions Competições, participações e eventos do aluno (positivos e negativos)
Notifications Templates, eventos de domínio, fila e preferências
Dashboards Visões agregadas para professor, responsável e aluno

Fase 2 — Módulos Avançados (10 módulos)

Módulo Descrição
Wellbeing Check-ins de humor/energia/engajamento, indicadores CASEL e alertas cruzados
Health Perfil de saúde, registro de ocorrências e encaminhamentos profissionais
MFA/Security Autenticação multi-fator TOTP com tokens parciais
Communication Conversas bidirecionais família-escola e solicitação de reuniões
Targets & Groups Metas de aprendizagem por habilidade e grupos flexíveis de alunos
Enrichment Trilhas de enriquecimento: olimpíadas, projetos, desafios e eletivas
Lesson Planning Planos de aula com habilidades-alvo e banco de recursos pedagógicos
Formative Portfólios digitais, entradas de evidência/reflexão e autoavaliação
AI & Insights Registro de modelos/execuções, sugestões aprováveis (human-in-the-loop) e feedback
Student Dashboard Dashboard agregado do aluno: notas, habilidades, metas, bem-estar e trilhas

Integração com Provedores de IA

Componente Descrição
Providers Anthropic (Claude), OpenAI (GPT-4o) e Google Gemini — abstrações intercambiáveis
Pipelines 5 pipelines de análise: risco acadêmico, PEI, intervenção, plano de aula e resumo semanal
Prompts Templates Jinja2 versionados em português brasileiro
Sanitizer Anonimização automática de dados pessoais antes de enviar ao provedor
Rate Limiting Controle de requisições por hora e orçamento mensal por organização
Contexto Agregadores de dados do aluno, turma e PEI para alimentar os prompts

Começando

Pré-requisitos

  • Docker e Docker Compose v2+
  • Node.js 18+ e npm
  • Git

1. Clonar e configurar

git clone <repo-url> escola-inteligente
cd escola-inteligente

# Variáveis de ambiente
cp .env.example .env
cp mobile/.env.example mobile/.env

O .env padrão já funciona para desenvolvimento local — não é necessário alterar nada na primeira vez.

2. Subir o backend

docker compose up -d

Isso inicia:

  • PostgreSQL 16 com pgvector na porta 5432 (usuário: escola, senha: escola_dev)
  • FastAPI na porta 8000 com hot-reload

O script scripts/init-db.sql cria automaticamente o schema school_mgmt, as extensões (pgcrypto, citext, vector) e o banco de testes.

docker compose ps   # ambos devem estar "running (healthy)"

3. Rodar migrations

docker compose exec -T app bash -c "PYTHONPATH=/app alembic upgrade head"

Cria ~80 tabelas no schema school_mgmt (10 migrations).

4. Popular com dados de demonstração

Execute todos os seeds para ter dados em todas as telas:

# Seed principal — org, escola, 8 alunos, professores, turma 6A, 5 disciplinas,
# aulas (4 semanas), avaliações, habilidades, PEI, intervenções, competições,
# eventos, notificações, conversas e reuniões
docker compose exec -T app bash -c "PYTHONPATH=/app python -m scripts.seed"

# Metas de aprendizagem (6) e grupos flexíveis (3 com 9 membros)
docker compose exec -T app bash -c "PYTHONPATH=/app python -m scripts.seed_targets_groups"

# Trilhas de enriquecimento (3 trilhas, 10 módulos, 9 inscrições)
docker compose exec -T app bash -c "PYTHONPATH=/app python -m scripts.seed_enrichment"

# Planos de aula (3 planos, 3 vínculos de habilidades, 5 recursos pedagógicos)
docker compose exec -T app bash -c "PYTHONPATH=/app python -m scripts.seed_lesson_planning"

# Dados de IA (2 modelos, 5 runs, 8 sugestões em vários status, feedbacks)
docker compose exec -T app bash -c "PYTHONPATH=/app python -m scripts.seed_ai"
Ver todos os dados criados pelos seeds
Módulo O que é criado
Organização/Escola 1 org, 1 escola
Pessoas 8 alunos, 2 professores, 1 coordenador, 1 admin, 2 responsáveis
Acadêmico 1 ano letivo, 2 bimestres, 1 turma (6A), 5 disciplinas (MAT, POR, CIE, HIS, GEO), 8 matrículas
Ensino Grade horária, ~80 aulas (4 semanas), frequência para todas
Avaliação Avaliações com rubricas e notas para todos os alunos
Habilidades 10 skills com mastery calculado para 8 alunos
PEI 2 PEIs (Gabriel=approved, Julia=draft) com objetivos e estratégias
Intervenções 2 intervenções (Gabriel=active, Julia=approved)
Competições Olimpíada de Matemática com participações
Eventos Eventos positivos e negativos para alunos
Observações 8 observações de professores
Notificações Notificações para todos os perfis
Bem-estar Check-ins e indicadores CASEL
Saúde Perfis de saúde, ocorrências, encaminhamentos
Comunicação 4 conversas com mensagens, 3 solicitações de reunião
Metas 6 metas de aprendizagem por habilidade
Grupos 3 grupos flexíveis (Reforço Frações, Desafio Matemático, Clube Leitura)
Trilhas 3 trilhas (OBMEP, Ciência Cidadã, Desafio Leitura) com módulos e inscrições
Planos de aula 3 planos (delivered, ready, draft) com habilidades-alvo
Recursos 5 recursos pedagógicos (vídeo, jogo, exercício, leitura, ferramenta)
IA 2 modelos, 5 runs de exemplo, 8 sugestões em vários status, feedbacks

5. Configurar IA (opcional)

Para usar os pipelines com provedores reais, adicione ao menos uma API key no .env:

ANTHROPIC_API_KEY=sk-ant-api03-...    # Anthropic (padrão) — recomendado
OPENAI_API_KEY=sk-...                 # OpenAI (opcional)
GOOGLE_AI_API_KEY=AIzaSy...           # Google Gemini (opcional)

Depois recrie o container: docker compose up -d app --force-recreate

Sem API key? O sistema funciona normalmente — a tela de sugestões exibe dados semeados. Os pipelines só executam quando disparados e retornam erro se nenhuma chave estiver configurada.

Configurações adicionais de IA
Variável Padrão Descrição
DEFAULT_AI_PROVIDER anthropic Provider padrão (anthropic, openai ou gemini)
DEFAULT_AI_MODEL claude-sonnet-4-5-20250514 Modelo padrão para o provider Anthropic
AI_MAX_TOKENS 4096 Máximo de tokens por request
AI_TEMPERATURE 0.3 Temperatura (0 = determinístico, 1 = criativo)
AI_MONTHLY_BUDGET_USD 100.0 Orçamento mensal em USD (bloqueia se exceder)
AI_RATE_LIMIT_PER_HOUR 60 Máximo de execuções por hora

6. Iniciar o frontend

cd mobile
npm install
npx expo start --web --port 8082

O frontend roda na porta 8082, já configurada no CORS do backend. Para outra porta, atualize CORS_ORIGINS no .env e recrie o container.

7. Acessar

Serviço URL Descrição
Frontend http://localhost:8082 Aplicação web (React Native/Expo)
API http://localhost:8000 Backend FastAPI
Swagger http://localhost:8000/docs Documentação interativa da API
Health check http://localhost:8000/health Status do servidor

Contas de Demonstração

Todas usam a senha Senha@123:

Perfil Email Acesso
Admin admin@escola-inteligente.local Acesso completo a todas as telas
Professor (Mat, Cie, His) joao@escola-inteligente.local Dashboard professor, turma 6A, aulas, notas
Professor (Por, Geo) ana@escola-inteligente.local Dashboard professor, turma 6A, aulas, notas
Coordenador coordenador@escola-inteligente.local Visão coordenação, PEI, intervenções
Responsável (mãe de Lucas e Maria) patricia@email.com Dashboard filhos, notas, frequência, comunicação
Responsável (pai de Pedro e Julia) roberto@email.com Dashboard filhos, notas, frequência, comunicação

Dica: use admin@escola-inteligente.local para navegar por todas as telas. Para testar a visão do responsável, use patricia@email.com.


Mapa de Telas

Após login com a conta Admin:

Tab Telas disponíveis
Início Dashboard do professor/coordenador · Sugestões da IA (abas Sugestões e Custos) · Pipelines de IA · Detalhe da sugestão
Alunos Lista de alunos · Grupos de aprendizagem · Trilhas de enriquecimento
Aluno → Perfil Visão geral (dashboard) · Boletim · Habilidades · PEI (com botão "Análise da IA") · Bem-estar · Saúde · Metas · Portfólio · Eventos
Turmas Turma 6A → por disciplina: Aulas · Avaliações · Planos de aula (com botão "Sugestões da IA")
Comunicação Notificações · Conversas (chat) · Solicitações de reunião
Perfil Dados da conta · Preferências · Segurança (MFA)

Integração com IA

Provedores suportados

Provider SDK Modelos Variável
Anthropic (padrão) anthropic Claude Sonnet 4.5, Claude Haiku 4.5 ANTHROPIC_API_KEY
OpenAI openai GPT-4o, GPT-4o-mini OPENAI_API_KEY
Google Gemini google-genai Gemini 2.0 Flash GOOGLE_AI_API_KEY

Cada provider implementa a mesma interface (AiProvider), permitindo trocar entre eles via configuração sem alterar código. O custo é calculado automaticamente por provider/modelo.

Pipelines disponíveis

Pipeline O que faz Dados analisados Onde disparar
risk_alert Identifica alunos em risco acadêmico Frequência, notas, habilidades em declínio, bem-estar Tela Pipelines de IA
pei_analysis Analisa progresso do PEI e sugere ajustes PEI com objetivos, estratégias, habilidades, frequência Botão "Análise da IA" no PEI
intervention_suggestion Sugere intervenções para alunos com lacunas Gaps de habilidade, histórico de intervenções Tela Pipelines de IA
lesson_adaptation Sugere adaptações ao plano de aula Perfil da turma, alunos com PEI Botão "Sugestões da IA" no plano
weekly_summary Gera resumo semanal para responsáveis Frequência, notas, bem-estar, eventos Tela Pipelines de IA

Fluxo human-in-the-loop

Pipeline disparado (manual ou automático)
  → Dados do aluno/turma agregados e anonimizados
    → Prompt em PT-BR enviado ao provedor de IA
      → Resposta JSON parseada em sugestões
        → AiRun registrado (tokens, custo, latência)
          → AiSuggestion(s) criada(s) com status "proposed"
            → Coordenador/professor revisa no app
              → Aprovar ou rejeitar (com motivo)
                → Se aprovada → marcar como "applied"
                  → Registrar feedback (funcionou? impacto?)

Telas de IA no frontend

Tela Caminho O que faz
Sugestões da IA Início → Sugestões da IA Lista com filtro por status. Aprovar, rejeitar e dar feedback.
Custos Sugestões da IA → aba "Custos" Custo mensal, execuções, tokens, breakdown por pipeline.
Pipelines Sugestões da IA → ícone pipe Lista de pipelines com botão "Executar".
Detalhe Toque em qualquer sugestão Texto completo, racional, confiança, dados do run e feedbacks.
Análise IA no PEI Aluno → PEI → "Análise da IA" Dispara pei_analysis para o PEI do aluno.
Sugestões no plano Turma → Plano → "Sugestões da IA" Dispara lesson_adaptation para a turma.

Segurança e privacidade da IA

  • Anonimização automática — nomes reais substituídos por "Aluno A", "Aluno B". CPF, telefone e email nunca são enviados.
  • Rastreabilidade — toda execução grava quem disparou, modelo usado, tokens consumidos e custo.
  • Rate limiting — máximo de execuções por hora (padrão: 60).
  • Budget mensal — bloqueia se o custo do mês exceder o orçamento (padrão: $100).
  • Human-in-the-loop — nenhuma sugestão é aplicada sem aprovação humana.

Endpoints da API de IA

Método Rota Descrição
POST /api/v1/schools/{id}/ai-pipelines/{name}/trigger Disparar pipeline (background)
GET /api/v1/ai-pipelines Listar pipelines disponíveis
GET /api/v1/organizations/{id}/ai-costs?month=YYYY-MM Resumo de custos do mês
POST /api/v1/ai-suggestions Criar sugestão
GET /api/v1/ai-suggestions?status=&target_entity_type= Listar sugestões (com filtros)
PUT /api/v1/ai-suggestions/{id}/review Aprovar/rejeitar sugestão
PUT /api/v1/ai-suggestions/{id}/apply Marcar como aplicada
POST /api/v1/ai-suggestions/{id}/feedback Registrar feedback
GET /api/v1/ai-suggestions/{id}/feedback Listar feedbacks
POST /api/v1/organizations/{id}/ai-models Registrar modelo
GET /api/v1/organizations/{id}/ai-models Listar modelos
POST /api/v1/ai-runs Registrar execução
GET /api/v1/ai-runs Listar execuções
GET /api/v1/ai-runs/{id} Detalhe da execução

Testes

Os testes rodam contra PostgreSQL real (escola_inteligente_test).

# Todos (388 testes)
docker compose exec -T app bash -c "PYTHONPATH=/app python -m pytest tests/ -v"

# Por módulo
docker compose exec -T app bash -c "PYTHONPATH=/app python -m pytest tests/test_auth.py -v"
docker compose exec -T app bash -c "PYTHONPATH=/app python -m pytest tests/test_ai_pipelines.py -v"
Cobertura completa (22 arquivos, 388 testes)
Arquivo Testes O que cobre
test_auth.py 16 Auth, registro, login, logout, tokens, forgot/reset password
test_rbac.py 6 Roles, permissões, escopo
test_grades.py 8 Avaliações, rubricas, notas, boletim
test_pei_workflow.py 11 PEI completo: draft → review → approved → archived
test_mastery.py 14 Recência, confiança, trend, gaps, upsert
test_wellbeing.py 17 Check-ins, tendências, indicadores CASEL, alertas
test_health.py 24 Perfil, ocorrências, encaminhamentos, API
test_mfa.py 18 Setup TOTP, verificação, challenge, delete
test_communication.py 23 Conversas, mensagens, reuniões, workflow
test_targets_groups.py 26 Metas, unicidade, grupos, membros
test_enrichment.py 24 Trilhas, módulos, inscrições, workflow
test_lesson_planning.py 26 Planos, skills sync, workflow, recursos
test_formative.py 23 Portfólios, entradas, autoavaliações
test_ai_insights.py 25 Modelos, runs, sugestões, workflow, feedback
test_ai_providers.py 12 Providers mockados, registry, cost estimation
test_ai_sanitizer.py 12 Anonimização, PII removal, entity map
test_ai_prompts.py 6 Renderização de templates Jinja2
test_ai_risk_pipeline.py 17 Context aggregator, pipeline E2E com mock
test_ai_pipelines.py 20 Todos os pipelines com mock provider
test_ai_rate_limit.py 3 Rate limiting por hora
test_ai_budget.py 5 Budget check mensal, bloqueio
test_student_dashboard.py 9 Dashboard agregado com múltiplos módulos

Estrutura do Projeto

escola-inteligente/
├── app/                                # Backend Python/FastAPI
│   ├── main.py                         # App factory + routers
│   ├── config.py                       # pydantic-settings (.env)
│   ├── core/                           # Infraestrutura compartilhada
│   │   ├── database.py                 #   async engine, sessionmaker, Base
│   │   ├── base_model.py              #   UUIDPrimaryKey, TimestampMixin, SoftDeleteMixin
│   │   ├── security.py                #   JWT, bcrypt, OAuth, partial tokens
│   │   ├── dependencies.py            #   get_db, get_current_user, require_permission
│   │   ├── exceptions.py             #   NotFound, Forbidden, BusinessRuleViolation
│   │   ├── pagination.py             #   PageParams, PageResponse
│   │   └── middleware.py              #   RequestId (ASGI puro)
│   └── modules/
│       ├── tenant/                     # Organizações e Escolas
│       ├── identity/                   # Auth, Contas, RBAC, MFA
│       ├── people/                     # Alunos, Staff, Responsáveis
│       ├── academic/                   # Anos, Turmas, Disciplinas, Matrículas
│       ├── teaching/                   # Grade, Aulas, Frequência
│       ├── assessment/                 # Avaliações, Rubricas, Notas
│       ├── inclusion/                  # Condições, Acomodações, PEI
│       ├── personalization/            # Skills, Mastery, Intervenções, Metas, Grupos
│       ├── competitions/               # Competições, Eventos
│       ├── notifications/              # Templates, Fila, Preferências
│       ├── dashboards/                 # Agregações (professor, responsável, aluno)
│       ├── wellbeing/                  # Check-ins, Indicadores CASEL
│       ├── health/                     # Saúde, Ocorrências, Encaminhamentos
│       ├── communication/              # Conversas, Mensagens, Reuniões
│       ├── enrichment/                 # Trilhas, Módulos, Inscrições
│       ├── lesson_planning/            # Planos de Aula, Recursos Pedagógicos
│       ├── formative/                  # Portfólios, Entradas, Autoavaliação
│       └── ai/                         # IA & Insights
│           ├── providers/              #   Anthropic, OpenAI, Gemini
│           ├── pipelines/              #   Risk, PEI, Intervenção, Aula, Resumo
│           ├── prompts/templates/      #   Templates Jinja2 (PT-BR)
│           ├── context/                #   Agregadores (aluno, turma, PEI)
│           ├── sanitizer.py            #   Anonimização de PII
│           ├── rate_limiter.py         #   Rate limiting por hora
│           └── budget.py               #   Controle de orçamento mensal
├── mobile/                             # Frontend React Native/Expo
│   ├── app/                            # Expo Router (file-based routing)
│   │   ├── _layout.tsx                 #   Root layout (providers, auth gate, MFA)
│   │   ├── (auth)/                     #   Login, forgot/reset password, MFA challenge
│   │   └── (app)/                      #   Grupo protegido (autenticado)
│   │       ├── (home)/                 #     Dashboard, Sugestões IA, Pipelines, Custos
│   │       ├── (students)/             #     Alunos, perfil, grupos, trilhas
│   │       ├── (classes)/              #     Turmas, aulas, avaliações, planos
│   │       ├── (notifications)/        #     Comunicação, conversas, reuniões
│   │       └── (profile)/              #     Conta, segurança MFA
│   └── src/
│       ├── api/                        #   Camada de API (Axios)
│       ├── hooks/                      #   TanStack Query hooks
│       ├── contexts/                   #   AuthContext
│       ├── components/                 #   UI, forms, feedback, layout
│       ├── types/                      #   TypeScript types
│       └── theme/                      #   Material Design 3
├── migrations/                         # Alembic (10 migrations)
├── scripts/                            # Seeds e utilitários
├── tests/                              # 388 testes (22 arquivos)
├── docs/                               # Documentação
├── docker-compose.yaml
├── Dockerfile
└── pyproject.toml

Cada módulo backend segue a convenção: models.pyschemas.pyservice.pyrouter.py.


Regras de Negócio

PEI Workflow

draft → in_review → approved → archived
                  ↘ draft (rejeição)
approved → in_review (revisão)
  • PEI só vai para in_review se tiver ≥ 1 goal
  • PEI só vai para approved se todos os goals tiverem owner
  • Apenas 1 PEI approved por aluno por vez

Cálculo de Mastery

  • Evidências ponderadas por recência: 30d → 1.0 · 30-90d → 0.7 · 90-180d → 0.4 · >180d → 0.2
  • Trend: mastery atual vs 30 dias atrás
  • Confidence: min(1.0, evidências / 10)
  • Gap: mastery < 0.4 e confidence ≥ 0.3

IA — Human-in-the-Loop

proposed → approved → applied   (ou proposed → rejected)
  • Apenas proposed pode ser aprovada/rejeitada
  • Apenas approved pode ser aplicada
  • Feedback registrado após aplicação

Plano de Aula

draft → ready → delivered → revised
  • Apenas draft pode ser deletado

Trilhas de Enriquecimento

invited → accepted → active → completed   (ou invited → declined)

Comandos Úteis

Backend

ruff check . && ruff format .                    # Lint e format
mypy app/                                         # Type check

# Migrations
docker compose exec -T app bash -c "PYTHONPATH=/app alembic revision --autogenerate -m 'descrição'"
docker compose exec -T app bash -c "PYTHONPATH=/app alembic upgrade head"
docker compose exec -T app bash -c "PYTHONPATH=/app alembic downgrade -1"

Frontend

cd mobile
npm install                          # Instalar dependências
npx expo start --web --port 8082     # Dev server (web)
npx expo run:android                 # Android
npx expo run:ios                     # iOS
npx eslint . && npx prettier --check .  # Lint

Ferramentas de Desenvolvimento

# pgAdmin — interface web para PostgreSQL
docker compose --profile tools up -d pgadmin
# → http://localhost:5050 (admin@escola.local / admin)

# Mailpit — servidor SMTP fake para emails
docker compose --profile tools up -d mailpit
# → http://localhost:8025

Troubleshooting

Frontend dá erro de CORS

O .env precisa incluir a porta do frontend em CORS_ORIGINS. Após alterar, recrie o container:

docker compose up -d app --force-recreate
Migration falha com "relation already exists"

O banco já tem as tabelas. Para resetar do zero:

docker compose down -v
docker compose up -d
docker compose exec -T app bash -c "PYTHONPATH=/app alembic upgrade head"
Seed falha com "duplicate key"

Os seeds não são idempotentes. Resete o banco (ver acima) e rode novamente.

Container app reinicia em loop

Verifique os logs: docker compose logs app. Causa comum: banco ainda não está pronto. Aguarde e tente docker compose restart app.

Pipeline de IA: "Unknown AI provider" ou "API key not configured"

Verifique se a API key está no .env e recrie o container:

docker compose exec app env | grep AI_KEY
docker compose up -d app --force-recreate
Pipeline de IA: "Rate limit exceeded" ou "Budget exceeded"

O sistema limita execuções por hora (AI_RATE_LIMIT_PER_HOUR, padrão 60) e por mês (AI_MONTHLY_BUDGET_USD, padrão $100). Ajuste no .env.

Frontend não conecta na API (Network Error)

Verifique se o backend está rodando: curl http://localhost:8000/health. No celular/emulador, use o IP da máquina:

EXPO_PUBLIC_API_URL=http://192.168.x.x:8000

Documentação

Arquivo Conteúdo
docs/schema_escola_inteligente.sql DDL completo (~80 tabelas)
docs/schema_escola_inteligente.md Dicionário de dados detalhado
docs/MVP-implementation-plan.md Plano de implementação — Fase 1
docs/fase2-implementation-plan.md Plano de implementação — Fase 2
docs/ai-integration-plan.md Plano de integração com provedores de IA
docs/funcionalidades_escola_inteligente_ddd.md Funcionalidades por bounded context
docs/diferenciais_roi_escola_inteligente.md Diferenciais, ROI e argumentos de venda
docs/vendas/apresentacao-escola-inteligente.md Documento comercial para diretores
CLAUDE.md Guia completo para o Claude Code

Licença

Proprietary — Todos os direitos reservados.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages