SIGA - Sistema Inteligente de Gestão Acadêmica

Hackathon Cultura Digital - Projeto em desenvolvimento.

---

📋 Tópicos

🔹 Descrição do Projeto
🔹 O Papel da IA
🔹 Funcionalidades e Requisitos
🔹 Tecnologias Utilizadas
🔹 Como Rodar a Aplicação
🔹 Boas Práticas de Desenvolvimento
🔹 Equipe

---

Descrição do Projeto

O SIGA (Sistema Inteligente de Gestão Acadêmica) é uma aplicação web desenvolvida para apoiar professores da educação básica no planejamento e criação de materiais didáticos.

Atendendo ao proposto no Hackathon de Cultura Digital, o sistema é focado no usuário único (o professor) e utiliza Inteligência Artificial Generativa para automatizar a criação de disciplinas, unidades de ensino, planos de aula, atividades avaliativas e slides, tudo estritamente alinhado à Base Nacional Comum Curricular (BNCC).

---

Uso de IA Assistida no Desenvolvimento 🤖

Conforme estabelecido no edital do Hackathon, é necessário esclarecer o papel da Inteligência Artificial no desenvolvimento desta solução. A equipe utilizou ferramentas de IA generativa como assistente de desenvolvimento, atuando como um "segundo cérebro" para otimizar o processo de criação do sistema.

Como a IA foi utilizada pela equipe:

1. Aceleração de Tarefas Repetitivas: Utilizamos IA para gerar código boilerplate, estruturas de componentes React, configurações de API e scripts de automação, reduzindo significativamente o tempo gasto em tarefas mecânicas.

2. Auxílio na Resolução de Problemas: A IA foi consultada para debugging, sugestões de otimização de código e esclarecimento de dúvidas técnicas sobre bibliotecas e frameworks utilizados no projeto.

3. Documentação e Padronização: Parte da documentação técnica e comentários de código foram elaborados com assistência de IA, garantindo clareza e consistência na comunicação técnica.

4. Prototipagem Rápida: Durante a fase inicial, a IA auxiliou na criação de protótipos de interface e na estruturação da arquitetura do sistema.

Domínio Total da Solução

É importante ressaltar que, embora a IA tenha sido uma ferramenta valiosa no processo de desenvolvimento, toda a equipe possui domínio completo sobre a solução implementada. Cada membro é capaz de explicar, modificar e expandir qualquer parte do código, desde a arquitetura do backend até os componentes do frontend. A IA foi utilizada como ferramenta de produtividade, não como substituta do conhecimento técnico da equipe.

---

Arquitetura de IA do Sistema ⚙️

O SIGA utiliza uma arquitetura sofisticada de Inteligência Artificial para gerar materiais didáticos personalizados e fornecer assistência completa aos professores. O sistema combina n8n (automação de workflows), Gemini API (modelo de linguagem), RAG (Retrieval-Augmented Generation) e Supabase (banco vetorial).

Fluxo de Geração de Conteúdo

graph LR
    A[Frontend - Dados do Usuário] --> B[n8n Workflow]
    B --> C[Validação e Extração]
    C --> D[Busca Vetorial - Supabase]
    D --> E[Embeddings - HuggingFace]
    E --> F[Gemini API + Prompt Contextualizado]
    F --> G[Validação 1 - Estrutura]
    G --> H[Validação 2 - BNCC]
    H --> I[Retorno ao Frontend]

Loading

Etapas do Processo:

1. Captura de Dados: O professor preenche informações no frontend (disciplina, série, tema da aula, etc.).

2. Orquestração n8n: Os dados são enviados para um workflow automatizado no n8n, que valida e extrai as informações mais relevantes.

3. Busca Vetorial (RAG): O sistema realiza uma busca semântica no Supabase utilizando embeddings gerados pelo HuggingFace. Essa busca recupera trechos relevantes da BNCC e diretrizes do MEC relacionados ao tema solicitado.

4. Geração com Gemini: O contexto recuperado é combinado com um prompt especializado e enviado para a Gemini API, que gera o conteúdo didático (plano de aula, atividade avaliativa ou slides).

5. Validações: O conteúdo gerado passa por duas camadas de validação:

   • Validação de Estrutura: Verifica se o formato está correto (seções obrigatórias, campos preenchidos).
   • Validação BNCC: Confirma o alinhamento com as competências e habilidades da Base Nacional Comum Curricular.

6. Entrega: O material validado é retornado ao frontend e apresentado ao professor, que pode editar, salvar ou exportar.

Assistente de Documentos Inteligente

Além da geração de materiais, o SIGA conta com um assistente de IA conversacional especializado na análise de documentos enviados (PDFs e materiais didáticos), que atua como um suporte direto ao professor:

Funcionalidades do Assistente:

• Análise de Documentos PDF:

  • Exemplo: "Resuma os pontos principais deste PDF sobre BNCC"
  • Resposta: Extrai e resume as competências e habilidades principais do documento.

• Consulta a Materiais Enviados:

  • Exemplo: "Com base no material que enviei, crie 3 perguntas de múltipla escolha"
  • Resposta: Gera questões contextualizadas diretamente do conteúdo do seu arquivo.

• Extração de Informações:

  • Exemplo: "Quais são as metas de aprendizagem citadas no plano de ensino anexo?"
  • Resposta: Identifica e lista as metas específicas encontradas no documento.

• Suporte Pedagógico sobre Arquivos:

  • Esclarecimento de dúvidas sobre conteúdos de PDFs.
  • Sugestões de atividades baseadas nos materiais enviados.
  • Adaptação de textos complexos para diferentes níveis de ensino.

O assistente utiliza um pipeline RAG especializado para processar os arquivos enviados pelo professor, garantindo que as respostas sejam baseadas estritamente nos documentos fornecidos.

---

Automação com n8n 🔗

O n8n é a plataforma de automação que orquestra a inteligência do sistema, atuando como o intermediário entre o Frontend e os modelos de IA (Gemini).

• Orquestração de Workflows: Gerencia fluxos complexos, desde a validação de entrada até a entrega de conteúdo estruturado.
• Integração BNCC: Realiza a busca vetorial no Supabase para garantir que todo conteúdo gerado esteja alinhado às habilidades da BNCC.
• Processamento de Respostas: Limpa e valida os dados retornados pela IA, garantindo que o frontend receba informações prontas para uso.

Para mais detalhes sobre a configuração e funcionamento dos fluxos, veja a documentação dedicada ao n8n.

---

Funcionalidades e Requisitos ✔️

O sistema atende integralmente aos Requisitos Funcionais (RF) do edital:

Código	Funcionalidade	Implementação no SIGA
RF01	Gerenciamento de Disciplinas	Cadastro de disciplinas (ex: Matemática, História) e associação com séries escolares.
RF02	Criação Manual de Unidades	Interface para o professor definir temas de aula manualmente e gerar conteúdo a partir deles.
RF03	Sugestão Automática (IA)	O sistema sugere trilhas de unidades/aulas baseadas na disciplina e ano selecionados, usando a BNCC.
RF04	Geração de Planos de Aula	Geração detalhada de roteiros de aula com objetivos, duração e metodologia.
RF05	Atividades Avaliativas	Criação automática de provas e exercícios com gabarito, contextualizados com a unidade.
RF06	Geração de Slides (Opcional)	Geração de estrutura de slides e conteúdo visual para suporte em sala de aula (Recurso Extra).

---

Tecnologias Utilizadas 📚

Frontend

• React: Interface moderna e reativa.
• Bun: Runtime e bundler de alta performance.
• Tailwind CSS: Estilização responsiva e tema dark/light mode.

Backend

• Python 3.11+: Linguagem base.
• FastAPI: Framework web de alta performance para a API.
• Supabase: Banco de dados (PostgreSQL) e Vetor Store para RAG.
• LangChain / LlamaIndex: Orquestração da IA e fluxos de RAG.
• Docker: Containerização da aplicação.

---

Pré-requisitos

Antes de começar, você precisará ter instalado em sua máquina:

• Bun (para o Frontend).
• Uma chave de API do Gemini(configurada no .env).

---

Como Rodar a Aplicação ▶️

1. Configuração do Ambiente

Clone o repositório:

git clone https://github.com/Felipe-Silva7/assistente-educacional
cd assistente-educacional

2. Executando o Backend (API)

O backend utiliza FastAPI e uv para gerenciamento de dependências.

Opção A: Usando Docker (Recomendado)

cd Backend
docker compose -f docker/docker-compose.yml up --build

Opção B: Execução Local com uv

1. Instale o uv.
2. Navegue até a pasta do backend e instale as dependências:

   cd Backend
   uv sync

3. Configure o arquivo .env com suas credenciais (Supabase, OpenAI/Gemini, etc).
4. Inicie o servidor:

   uv run uvicorn app.main:app --reload

O Backend estará rodando em http://localhost:8000. Acesse a documentação interativa em /api/v1/docs.

3. Executando o Frontend

O frontend utiliza React, TypeScript e Bun.

1. Instale o Bun.
2. Navegue até a pasta do frontend:

   cd Frontend

3. Instale as dependências e rode o servidor de desenvolvimento:

   bun install
   bun dev

O Frontend estará acessível em http://localhost:3000.

4. Acesso Remoto e Mobile (Ngrok)

O Ngrok é uma ferramenta que cria um túnel seguro do seu ambiente local para a internet, permitindo que você acesse seu projeto de qualquer lugar (como um celular) sem precisar configurar firewalls ou IPs públicos.

Configuração do Token

Antes de começar, você precisa configurar seu token de autenticação (authtoken) para liberar recursos como o uso de arquivos de configuração e evitar limites restritos:

1. Obtenha seu token em dashboard.ngrok.com.
2. Configure o token no arquivo Frontend/ngrok.yml ou via terminal:

   ngrok config add-authtoken SEU_TOKEN_AQUI

Como Rodar

Para testar a aplicação em dispositivos móveis ou redes externas utilizando o Ngrok, é necessário utilizar o Proxy Educacional incluído no projeto para garantir a compatibilidade de CORS e HMR.

1. Inicie o Backend e Frontend normalmente (portas 8000 e 3000).
2. Inicie o Proxy (em um novo terminal na pasta Frontend):

   bun run proxy.ts

   O proxy rodará em http://localhost:8080 e gerenciará o tráfego para ambos os servidores.

3. Inicie o Ngrok usando o arquivo de configuração (na pasta Frontend):

   ngrok start app --config=ngrok.yml

4. Acesse a URL HTTPS gerada pelo Ngrok no seu celular ou dispositivo externo.

O sistema detectará automaticamente o ambiente e ajustará as rotas da API para funcionar perfeitamente através do túnel.

---

Boas Práticas de Desenvolvimento 📌

Para garantir a organização e a qualidade do código durante o desenvolvimento do projeto, seguimos um fluxo de trabalho baseado em GitFlow Simplificado:

• Branch main: Reservada exclusivamente para o código em produção. É a versão estável e final entregue aos usuários.
• Branch develop: Branch principal de desenvolvimento. Todas as novas funcionalidades e correções são integradas aqui antes de irem para a main.
• Fluxo de Trabalho:
  • Não criamos branches adicionais a partir da develop. O desenvolvimento é feito diretamente ou integrado nela para manter a agilidade necessária.
• Commits:
  • Mensagens de commit claras e objetivas em Português.
  • Exemplos: feat: adicionei suporte a geração de slides, fix: corrigi erro de login no mobile.

---

Layout da Aplicação

Homepage

Login

Dashboard

Modals

Config

---

Desenvolvedores

Matheus Fernandes	Felipe Silva	Brenno Victor

---

Licença

Este projeto está sob a licença MIT.

Copyright ©️ 2026 - SIGA Team