backend-clinica-api/
├── docs/ -> Technical documentation and decision records
│ ├── database/ -> Database design and domain constraints
│ │ ├── database.md -> Database as contract and design rationale
│ │ ├── entidades.md -> Domain entities and responsibilities
│ │ └── regras-de-negocio.md -> Business rules enforced at DB and service level
│ │
│ ├── decisions/ -> Architectural and domain decisions (ADR-style)
│ │ ├── architecture-in-practice.md -> How layered architecture is applied
│ │ ├── database-location-decision.md -> Why database module lives inside src
│ │ ├── domain-decisions.md -> Domain modeling and boundary decisions
│ │ └── escopo-e-planejamento.md -> Scope definition and project planning
│ │
│ ├── diagrams/ -> Visual representations of the system
│ │ ├── architecture/
│ │ │ └── layered-architecture.drawio.png -> Layered architecture overview
│ │ └── domain/
│ │ └── er-diagram.png -> Entity-relationship diagram
│ │
│ ├── reports/ -> Consolidated technical reports
│ │ └── dossier/
│ │ └── technical-dossier.md -> Final technical dossier (portfolio artifact)
│ │
│ ├── infrastructure/ -> Environment and infrastructure setup
│ │ ├── backend-infrastructure-setup.md -> Local backend setup and dependencies
│ │ └── technical-report-architectural-stabilization.md -> Stabilization phase report
│ │
│ └── validation/ -> Manual validation and QA evidence
│ ├── README.md -> Validation index and scope
│ ├── setor-crud-validation.md -> Setor CRUD validation
│ ├── cargo-crud-validation.md -> Cargo CRUD validation
│ ├── funcionario-crud-validation.md -> Funcionário CRUD validation
│ └── relational-integrity-validation.md -> FK and relational integrity validation
│
├── src/ -> Application source code
│ ├── controllers/ -> HTTP layer (FastAPI endpoints)
│ │ ├── __init__.py
│ │ ├── setor_controller.py -> Setor endpoints
│ │ ├── cargo_controller.py -> Cargo endpoints
│ │ └── funcionario_controller.py -> Funcionário endpoints
│ │
│ ├── database/ -> Database configuration and metadata
│ │ ├── README.md -> Database module overview
│ │ ├── __init__.py
│ │ ├── base.py -> SQLAlchemy Declarative Base
│ │ ├── session.py -> Engine and session management
│ │ └── schema.sql -> SQL schema (database contract)
│ │
│ ├── domain/ -> Domain models (no business logic)
│ │ ├── __init__.py
│ │ ├── setor.py -> Setor entity
│ │ ├── cargo.py -> Cargo entity
│ │ └── funcionario.py -> Funcionário entity
│ │
│ ├── repositories/ -> Persistence layer (DB access only)
│ │ ├── __init__.py
│ │ ├── setor_repository.py -> Setor persistence logic
│ │ ├── cargo_repository.py -> Cargo persistence logic
│ │ └── funcionario_repository.py -> Funcionário persistence logic
│ │
│ ├── schemas/ -> Request/response validation schemas
│ │ ├── setor_schema.py -> Setor input/output schemas
│ │ ├── cargo_schema.py -> Cargo input/output schemas
│ │ └── funcionario_schema.py -> Funcionário input/output schemas
│ │
│ ├── services/ -> Business rules and orchestration
│ │ ├── __init__.py
│ │ ├── setor_service.py -> Setor business rules
│ │ ├── cargo_service.py -> Cargo business rules
│ │ └── funcionario_service.py -> Funcionário business rules
│ │
│ ├── __init__.py
│ └── main.py -> Application entry point
│
└──.gitignore
Nota: o projeto utiliza o padrão src-layout, onde
src/contém todos os pacotes reais da aplicação. Isso evita imports frágeis, colisões de nomes e dependência do diretório raiz.
Este projeto tem caráter educacional e técnico, com foco no aprendizado prático de desenvolvimento backend utilizando uma stack moderna e amplamente utilizada no mercado.
O objetivo principal é exercitar:
- modelagem de domínio
- definição e implementação de regras de negócio
- persistência em banco de dados relacional
- organização de código seguindo arquitetura em camadas
- documentação técnica e registro de decisões arquiteturais
O sistema simula um recorte reduzido de um contexto real, priorizando clareza arquitetural e qualidade técnica em vez de abrangência funcional.
Este projeto não tem como objetivo:
- desenvolver frontend ou interface gráfica
- implementar autenticação, autorização ou controle de acesso
- cobrir todos os domínios de uma clínica médica real
- tratar agendamentos, prontuários, faturamento ou integrações externas
- utilizar microserviços ou infraestrutura distribuída
- focar em performance, escalabilidade ou alta disponibilidade
Essas decisões são intencionais e visam manter o escopo controlado, permitindo aprofundamento técnico nos fundamentos de backend.
O desenvolvimento deste projeto foi acompanhado e organizado utilizando o GitHub Projects.
O board foi usado como ferramenta de gestão técnica para:
- organizar issues por fase e prioridade
- acompanhar o progresso das entregas
- registrar evolução incremental do backend
- consolidar decisões técnicas ao longo do desenvolvimento
- manter rastreabilidade entre tarefas, documentação e código
Cada etapa do projeto — desde modelagem inicial até estabilização arquitetural e documentação final — foi conduzida com base nesse fluxo.
Essa abordagem reflete uma prática próxima ao ambiente profissional, onde planejamento, execução e documentação evoluem juntos.
O desenvolvimento do projeto foi acompanhado utilizando o GitHub Projects, onde foram organizadas as issues, fases do projeto e o progresso técnico ao longo do tempo.
- Python — linguagem principal
- FastAPI — framework web para construção da API
- PostgreSQL — banco de dados relacional
- SQLAlchemy (2.0.45) — ORM para mapeamento objeto-relacional
- Git / GitHub — versionamento e organização do projeto
O backend segue o padrão de arquitetura em camadas, com separação clara de responsabilidades:
- API (Controllers) Camada de entrada HTTP. Recebe requisições, aplica validação de contrato via schemas, e delega a execução para os serviços.
- Service Camada central de regras de negócio, validações de domínio e orquestração de fluxos.
- Repository Camada responsável exclusivamente pelo acesso e persistência de dados.
- Domain Definição das entidades, conceitos e estrutura do domínio, alinhados ao schema do banco e às regras de negócio.
- Schemas (API Contracts) Definição dos contratos de entrada e saída da API (Pydantic), desacoplados do domínio e utilizados pelos controllers.
- Database (Infra) Infraestrutura de persistência: configuração do ORM, base declarativa e gerenciamento de sessões.
Essa abordagem favorece:
- código legível e previsível
- facilidade de testes
- baixo acoplamento
- evolução incremental do sistema
Este projeto está licenciado sob a Creative Commons Attribution–NonCommercial 4.0 International (CC BY-NC 4.0).
- Uso pessoal, acadêmico e educacional
- Estudo do código como referência técnica
- Forks para aprendizado, experimentação e aprimoramento
- Modificações e adaptações sem fins comerciais
- Compartilhamento com a devida atribuição ao autor
- Uso comercial de qualquer natureza
- Venda total ou parcial do código
- Inclusão do projeto em produtos ou serviços pagos
- Monetização direta ou indireta sem autorização prévia
Este repositório foi desenvolvido com foco educacional e técnico, como material de estudo e portfólio de arquitetura backend.
Se este projeto foi útil para você:
- ⭐ Considere dar uma estrela
- 🍴 Forks são bem-vindos para aprendizado e evolução técnica
- 📚 Uso acadêmico é explicitamente encorajado
Para usos comerciais, entre em contato com @lucaspaiva-lp.