Implement complete backend scraper with SQLite database and FastAPI REST API

[Copilot]

Adds production-ready scraper infrastructure for UAlg course data with normalized SQLite storage and REST API endpoints for data access.

Core Components

Database Schema (schema.sql)

• 8 normalized tables: levels, schools, areas, courses, modules, course_documents, course_area, module_course
• Indexed foreign keys with cascading deletes

Complete Scraper (src/scrape_ualg.py)

• Paginated course listing extraction
• Automatic PDF document downloads to data/docs/
• Rate limiting (1.5s) with exponential backoff (1.5^n, max 5s)
• Upsert operations prevent duplicates

REST API (src/api.py)

• GET /courses - filterable by level/school/area with pagination
• GET /courses/{id} - full details including modules and documents
• GET /levels|/schools|/areas - metadata endpoints
• GET /stats - aggregate statistics
• Auto-generated OpenAPI docs at /docs

Usage

from src.scrape_ualg import UAlgCourseScraper

scraper = UAlgCourseScraper()
scraper.init_db()
scraper.scrape_all_courses(limit=10)

make init-db        # Initialize database
make run-scraper    # Execute scraper
make run-api        # Start API server on :8000

Testing

35 tests with 80% coverage across scraper, API, and database operations. All SQL queries parameterized to prevent injection.

Notes

Original basic scraper (src/scraper.py) preserved for backward compatibility. Selectors in scrape_ualg.py are placeholder heuristics and need adjustment to actual DOM structure of UAlg site.

Original prompt

Prompt: Criação de Repositório Backend/Scraper – Monynha Softwares

Crie um para o projeto dsob a organização Monynha-Softwares (https://github.com/Monynha-Softwares) o back-end com scraper. O repositório deve seguir o modelo de monynha Softwares, conter somente o código do back-end e scraper (sem front-end por enquanto) e utilizar a licença MIT. Toda a documentação (README, comentários, arquivos de contribuição) deve ser em português. Siga as melhores práticas de programação colaborativa e organização de código, conforme descrito a seguir.

Estrutura e Conteúdo do Repositório

Nomeação adequada: escolha um nome claro e consistente com o propósito (ex.: monynha-backend-scraper).

Diretórios principais: crie pastas como src/ ou app/ para o código-fonte do scraper/back-end e tests/ para os testes automatizados. Separe o código de produção e os testes em diretórios distintos (de acordo com boas práticas de projeto Python).

Gerenciamento de dependências: inclua um arquivo requirements.txt (ou pyproject.toml/Pipfile) com todas as dependências. Adicione também um Makefile (ou script de gerenciamento) na raiz. Por exemplo, inclua no Makefile tarefas genéricas como init (que rode pip install -r requirements.txt) e test (que rode pytest tests).

Arquivos de configuração: adicione um .gitignore adequado (ex.: ignorar venv/, arquivos temporários, etc.), e diretório .github/workflows/ com workflow de CI para testes automatizados. Use ferramentas de linting e formatação (ex.: Flake8, Black) para manter estilo consistente (mesmo que não haja citação direta, isso é recomendação geral).

Readme inicial: crie README.md em português explicando o objetivo do projeto, instruções de instalação e uso. O README é o primeiro arquivo que visitantes veem, e junto com a licença e demais arquivos ajuda a alinhar expectativas do projeto.

Documentação e Licença

README: deve descrever o projeto, suas funcionalidades, dependências, instruções de instalação e execução, exemplos de uso e como executar os testes. Escreva em português claro e conciso. Deixe claro que a licença é MIT e liste os passos básicos para rodar o scraper/back-end. (Um bom README, junto com licença e diretrizes de contribuição, “ajuda a compartilhar expectativas e gerenciar contribuições”.)

LICENÇA: inclua um arquivo LICENSE com o texto padrão da licença MIT. A licença informa “o que se pode e não se pode fazer com o código” e garante direitos de uso abertos.

CONTRIBUTING e COC: adicione um CONTRIBUTING.md em português com orientações de como contribuir (padrões de código, fluxo de trabalho, código de conduta, etc.) e um CODE_OF_CONDUCT.md definindo normas de convivência na comunidade (boas práticas de interação).

Templates de issues/PR: crie templates em .github/ISSUE_TEMPLATE/ e .github/PULL_REQUEST_TEMPLATE/ para padronizar novas issues e pull requests (incentive descrições completas, checklist de testes, etc.). Isso ajuda a guiar contribuidores desde o início.

Boas Práticas de Colaboração

Fluxo de trabalho Git: use branch principal (main) estável e faça ramificações (branches) para cada feature ou correção. Realize revisões via pull requests, solicitando aprovação de pelo menos outro revisor antes de mesclar. Use issues para relatar bugs e planejar melhorias, e pull requests para discutir e revisar mudanças propostas.

Commits e mensagens: faça commits frequentes e atômicos, cada um com uma mensagem clara e descritiva. Mensagens detalhadas ajudam na manutenção e colaboração. Por exemplo, explique o “por quê” da mudança, não só o “quê”. Isso facilita o entendimento durante code reviews e históricos de mudanças.

Revisão de código: incentive revisões mútuas de código. Ao criar um PR, revise as mudanças de outro desenvolvedor e vice-versa. Isso diminui bugs, melhora a legibilidade e transmite conhecimento na equipe. Busque sempre legibilidade e adesão às convenções (ex.: PEP8 em Python).

Comunicação: use a seção de Issues para discussões específicas (relatar bugs, pedir melhorias) e comentários em Pull Requests para feedback de código. Mantenha um tom profissional e colaborativo, seguindo o Código de Conduta definido.

Testes Automatizados

Cobertura de testes: escreva testes automatizados para as funcionalidades do scraper e do back-end. Prefira testes de unidade independentes; cada teste deve ter um nome descritivo que indique claramente seu propósito. Use asserts para verificar resultados esperados. Por exemplo, teste a extração correta de dados, tratamento de erros, etc.

Independência dos testes: certifique-se de que cada teste não dependa de estados externos ou de outros testes. Use fixtures ou mocks se necessário. Isso garante que possam rodar isoladamente e em qualquer ordem.

Integração Contínua: configure um workflow de CI (ex.: GitHub Actions) para instalar dependências e executar a suíte de testes a cada push ou pull request. O GitHub Actions tem templates prontos para projetos Python, mas o essencial é que, em cada push, o ambiente virtual ...

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[marcelo-m7]

It is needed to improve the scrapping process.