# fgsantosti/algoritmosprogramacao architecture

> Architecture diagram of the GitHub repository fgsantosti/algoritmosprogramacao, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fgsantosti/algoritmosprogramacao
- Repository: https://github.com/fgsantosti/algoritmosprogramacao

## Overview

##### O que o repositório é hoje
Pelo *file tree*, isso é majoritariamente um **repositório educacional** de Python (muitos “Cap 02…Cap 09”, vários `Q*.py`, e vários notebooks `.ipynb`). Há também pequenos “apps” e exemplos de persistência:
- `app_agenda.py` + `Cap 09/agenda.py` + `Cap 09/agenda.txt` → indica um mini-sistema de agenda com **persistência em arquivo texto**.
- `Cap 09/login.py` → indica fluxo de autenticação simples (provável exemplo).
- `Cap 09/*.pickle` e scripts `cria_bin*.py` → exemplos de **persistência binária/pickle**.
- `app_tarefas.py` → outro mini-sistema CLI.

##### O que o projeto pretende entregar (README)
O README descreve um **Sistema de Gestão de Clínica Médica** (CLI ou GUI simples), com 4 módulos principais:
##### Prontuário simplificado (registro pós-consulta, vinculado a paciente e profissional)

**Conclusão para o diagrama:** o “sistema-alvo” é um **aplicativo monolítico local (CLI/GUI)** com módulos de domínio e alguma camada de persistência (arquivos `.txt` e/ou `.pickle`), inspirado nos exemplos do Cap 09.

##### Como ler a estrutura atual para extrair “componentes arquiteturais”

Como não há um pacote `src/` ou `clinic/` organizado, o jeito mais fiel é mapear por **clusters**:

##### Interface / Apps (pontos de entrada)
- `app_agenda.py`, `app_tarefas.py`
- (Potencialmente) `Cap 03/menu.py` (indica padrão de menu CLI)

##### Domínio (o que o sistema “faz”)
Ainda não existe explicitamente “pacientes.py / profissionais.py / consultas.py”, então no diagrama você deve representar **componentes esperados** (do README) e indicar que hoje eles estão “a implementar / dispersos em scripts”.

##### Persistência / armazenamento local
Evidências claras:
- Arquivo texto: `Cap 09/agenda.txt`, `Cap 09/numeros.txt`
- Pickle/binário: `Cap 09/data.pickle`, `Cap 09/mi.pickle`, scripts `cria_bin.py`, etc.

##### Utilitários / bibliotecas de apoio
- `Cap 08/biblioteca.py`, `chama_biblioteca.py` → padrão de “módulo utilitário”
- Vários scripts de string/matriz/etc. (não essenciais ao sistema da clínica, mas mostram estilo)

**Moral:** o diagrama deve separar “o sistema da clínica” do “material didático”, ou então explicitamente mostrar que o repositório contém ambos.

##### Diagrama 1 — C4 / System Context (L1)
**Pergunta que responde:** “quem usa e o que o sistema toca externamente?”

Elementos:
- **Atendente/Recepção (Usuário)** → usa o sistema
- **Profissional de saúde (Usuário)** → usa o sistema (consulta prontuário / agenda)
- **Sistema de Gestão de Clínica** (o seu software)
- **Armazenamento local** (arquivos `.txt` / `.pickle`) como “dependência externa” (porque não é “código”, é infraestrutura local)
- (Opcional, mas citado no README) **GUI framework**: Tkinter/PySimpleGUI (se adotarem GUI)

Setas:
- Usuários → (CLI/GUI) → Sistema
- Sistema → Arquivos locais (ler/gravar)

##### Diagrama 2 — C4 / Containers (L2)
**Pergunta:** “quais são as grandes ‘caixas’ executáveis e seus contratos?”

Para este projeto (monolito local), os containers típicos são:
##### CLI App (ou GUI App)
- Ex.: “Menu / interação do usuário”
##### Core/Domain Layer (lógica do negócio)
- Pacientes, Profissionais, Consultas, Prontuário
##### Persistence Layer (repositórios/DAO)
- Implementações em arquivo texto e/ou pickle
##### Storage (o diretório/arquivos)
- `agenda.txt`, `*.pickle`, etc.

Setas típicas:
- CLI/GUI → Domain (chama casos de uso)
- Domain → Persistence (CRUD + queries)
- Persistence → Storage (I/O)

**Importante:** mesmo que hoje isso esteja tudo “em scripts”, o diagrama L2 deve representar essa separação, porque ela é a “arquitetura correta” do que o README pede. Você pode anotar: “atualmente acoplado em scripts; alvo: separar em camadas”.

##### Diagrama 3 — C4 / Components (L3) dentro do “Domain Layer”
**Pergunta:** “quais componentes reais existem (ou devem existir) e como conversam?”

Componentes que o README exige (e que devem estar no diagrama):
- **PacienteService**
- Casos de uso: criar/listar/buscar(atualizar/excluir)
- **ProfissionalService**
- CRUD + manutenção de agenda (dias/horários)
- **ConsultaService**
- Marcar/Remarcar/Cancelar/Listar
- **Conflito de agenda** (componente explícito: `ConflictChecker`)
- **ProntuarioService**
- Registrar atendimento pós-consulta e vincular paciente+profissional

Componentes de persistência (interfaces + implementações):
- `PacienteRepository` (FileTxt / Pickle)
- `ProfissionalRepository` (FileTxt / Pickle)
- `ConsultaRepository` (FileTxt / Pickle)
- `ProntuarioRepository` (FileTxt / Pickle)

Componentes auxiliares (cross-cutting):
- **Validação** (CPF, datas, telefone)
- **Autenticação** (se `Cap 09/login.py` for aproveitado)
- **Serialização** (pickle / parsing de texto)

Setas:
- CLI Menu → Services
- Services → Repositories
- ConsultaService → ConflictChecker → (ConsultaRepository + ProfissionalRepository)

##### (Opcional, mas altamente recomendável) Diagrama 4 — Modelo de Dados (ERD/UML simples)
Entidades e relações mínimas:
- **Paciente (CPF único)** 1—N **Consulta**
- **Profissional (CRM/COREN único)** 1—N **Consulta**
- **Consulta** 1—1/N **Prontuário** (depende se permite múltiplas evoluções por consulta)
- Índices/uniqueness: CPF, CRM/COREN
- Regras: Consulta tem (data, hora, paciente_id, profissional_id, status)

Esse diagrama é crucial porque “conflito de agenda” depende diretamente dessas chaves e relações.

#### 4) Relacionar explicitamente com os arquivos que você tem (para ficar “acurado” ao repositório)

Mesmo que o sistema da clínica não esteja implementado como pacote, você pode ancorar o diagrama no que existe:

- **Persistência local (evidência no repo):**
- `Cap 09/agenda.txt` (texto)
- `Cap 09/*.pickle` (binário)
- Scripts `cria_txt.py`, `cria_bin.py` (geração)
- **Padrão de menu/CLI (evidência):**
- `Cap 03/menu.py`
- `app_agenda.py`, `app_tarefas.py` como executáveis
- **Módulos utilitários (evidência):**
- `Cap 08/biblioteca.py`

No diagrama, use notas do tipo:
- “Storage atual: txt/pickle (vide Cap 09/*)”
- “Entrada atual: CLI (vide app_*.py)”
- “Material de estudo: Cap 02–09 e notebooks (fora do runtime do sistema)”

Isso evita o erro comum de desenhar uma arquitetura “enterprise” (API + DB + serviços) que não condiz com o projeto.

##### Padrões/princípios arquiteturais a destacar (específicos para este caso)

- **Monólito local, camadas (UI → Services → Repositories → Storage)**
Excelente para CLI/GUI simples.
- **Separação de domínio vs persistência**
Principalmente porque “txt/pickle” pode ser trocado depois por SQLite sem reescrever regra de negócio.
- **Regras de negócio explícitas**
- Conflito de agenda como componente próprio (não escondido no menu).
- **Entidades com IDs únicos**
- CPF e CRM/COREN como chaves naturais.

##### Como desenhar (convenções visuais que deixam o diagrama “executivo e preciso”)

Inclua no desenho:

##### Rótulos claros
- Nome do componente + responsabilidade curta
- Ex.: “ConsultaService — remarcação/cancelamento + validação de conflitos”

##### Setas direcionais (fluxo)
- “chama”, “lê/grava”, “valida”
- Diferencie “dependency” (pontilhado) vs “data flow” (linha cheia), se quiser elevar a precisão.

##### Cores / formas por tipo
Sugestão simples:
- **Azul:** UI (CLI/GUI)
- **Verde:** Domínio/Services
- **Laranja:** Persistência/Repositories
- **Cinza:** Storage (arquivos) e externos (Tkinter, OS filesystem)

##### Anotações de decisão (ADR-style em mini-notes)
- “Persistência inicial em txt/pickle”
- “Possível migração para SQLite”
- “Autenticação opcional (base: Cap 09/login.py)”

##### Checklist final: “não overthink”, mas decomponha bastante

Para este projeto, “ser detalhado” significa:
- Separar **Paciente / Profissional / Consulta / Prontuário** (não agrupar tudo em “Backend”)
- Separar **UI** de **Regras de negócio**
- Separar **Repositórios** do **Storage**
- Tornar **conflito de agenda** um bloco explícito
- Indicar **formatos de persistência** reais do repo (`.txt` / `.pickle`)

Se você seguir C4 (L1-L3) + um ERD, você terá um diagrama ao mesmo tempo:
- fiel ao repositório atual (scripts + arquivos),
- alinhado ao sistema pedido no README,
- e estruturado para evolução (GUI, SQLite, testes, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% L1 — C4 System Context
%% =========================
subgraph "L1 — Contexto do Sistema"
direction TB

U1["Atendente/Recepção\n(Usuário)"]:::actor
U2["Profissional de Saúde\n(Usuário)"]:::actor

SYS["Sistema de Gestão de Clínica\n(Monólito local CLI/GUI)"]:::system

GUI["Framework GUI (opcional)\nTkinter/PySimpleGUI"]:::external
FS["Sistema de Arquivos Local\n(Infra)"]:::external
end

U1 -->|"usa"| SYS
U2 -->|"usa"| SYS
GUI -.->|"UI_opcional"| SYS
SYS -->|"ler_gravar"| FS

%% =========================
%% L2 — C4 Containers
%% =========================
subgraph "L2 — Containers (alvo arquitetural)"
direction TB

subgraph "Interface (UI)"
direction TB
CLI1["CLI App\n(app_agenda / app_tarefas)"]:::ui
CLIMenu["Menu CLI\n(padrão de navegação)"]:::ui
end

subgraph "Aplicação/Domínio (Core)"
direction TB
Domain["Domain Layer\n(regras de negócio)"]:::domain
end

subgraph "Persistência"
direction TB
Persist["Persistence Layer\n(Repos/DAO)"]:::persistence
Serializer["Serialização\n(txt_parse / pickle)"]:::persistence
end

subgraph "Storage (atual no repo)"
direction TB
TxtStore[("Arquivos .txt\n(ex.: agenda.txt, numeros.txt)")]:::storage
PickleStore[("Arquivos .pickle\n(ex.: data.pickle, mi.pickle)")]:::storage
end
end

CLI1 -->|"chama"| CLIMenu
CLIMenu -->|"executa_casos_de_uso"| Domain
Domain -->|"CRUD_queries"| Persist
Persist -->|"usa"| Serializer
Serializer -->|"I_O"| TxtStore
Serializer -->|"I_O"| PickleStore
TxtStore -->|"armazenado_em"| FS
PickleStore -->|"armazenado_em"| FS

%% =========================
%% L3 — Components (Domain + Persistence)
%% =========================
subgraph "L3 — Componentes (detalhamento dentro do monólito)"
direction TB

subgraph "Domain Services (README)"
direction TB
PacienteSvc["PacienteService\n(CRUD + busca)"]:::domain
ProfissionalSvc["ProfissionalService\n(CRUD + agenda)"]:::domain
ConsultaSvc["ConsultaService\n(marcar/remarcar/cancelar)\n+ conflitos"]:::domain
ProntuarioSvc["ProntuarioService\n(registro pós-consulta)\n(vincula paciente+profissional)"]:::domain

ConflictChecker["ConflictChecker\n(detecta conflitos de agenda)"]:::domain
Validator["Validação\n(CPF, datas, telefone)"]:::domain
Auth["Autenticação (opcional)\n(base em exemplo de login)"]:::domain
end

subgraph "Repositories (interfaces + impl em arquivos)"
direction TB
PacienteRepo["PacienteRepository\n(FileTxt/Pickle)"]:::persistence
ProfissionalRepo["ProfissionalRepository\n(FileTxt/Pickle)"]:::persistence
ConsultaRepo["ConsultaRepository\n(FileTxt/Pickle)"]:::persistence
ProntuarioRepo["ProntuarioRepository\n(FileTxt/Pickle)"]:::persistence
end

subgraph "Evidências no repo (componentes existentes)"
direction TB
AgendaDomainExample["Agenda (exemplo Cap 09)\n(lógica + operações)"]:::domain
UtilLib["Biblioteca utilitária\n(funções reutilizáveis)"]:::util
UtilUse["Exemplo de uso da biblioteca"]:::util
TxtCreator["Script de criação/gravação .txt"]:::persistence
BinCreator["Script de criação/gravação .pickle"]:::persistence
BinCreatorSimple["Script .pickle (simples)"]:::persistence
end
end

%% UI -> Domain
CLIMenu -->|"criar_listar_buscar"| PacienteSvc
CLIMenu -->|"criar_listar_buscar"| ProfissionalSvc
CLIMenu -->|"marcar_remarcar_cancelar"| ConsultaSvc
CLIMenu -->|"registrar_atendimento"| ProntuarioSvc
CLIMenu -->|"login"| Auth

%% Cross-cutting
PacienteSvc -->|"valida"| Validator
ProfissionalSvc -->|"valida"| Validator
ConsultaSvc -->|"valida"| Validator
ProntuarioSvc -->|"valida"| Validator

ConsultaSvc -->|"checa_conflito"| ConflictChecker
ConflictChecker -->|"consulta_agenda"| ProfissionalRepo
ConflictChecker -->|"consulta_existentes"| ConsultaRepo

%% Services -> Repos
PacienteSvc -->|"persistir"| PacienteRepo
ProfissionalSvc -->|"persistir"| ProfissionalRepo
ConsultaSvc -->|"persistir"| ConsultaRepo
ProntuarioSvc -->|"persistir"| ProntuarioRepo

%% Repos -> Persistence Layer
PacienteRepo -->|"I_O"| Persist
ProfissionalRepo -->|"I_O"| Persist
ConsultaRepo -->|"I_O"| Persist
ProntuarioRepo -->|"I_O"| Persist

%% Repo examples anchored in existing scripts/files
AgendaDomainExample -.->|"inspira"| ConsultaSvc
AgendaDomainExample -.->|"inspira"| ProfissionalSvc
UtilLib -.->|"apoia"| Validator
UtilUse -.->|"demonstra"| UtilLib

TxtCreator -->|"gera_atualiza"| TxtStore
BinCreator -->|"gera_atualiza"| PickleStore
BinCreatorSimple -->|"gera_atualiza"| PickleStore

%% =========================
%% Modelo de dados (ERD simples)
%% =========================
subgraph "Modelo de Dados (mínimo para conflitos e vínculos)"
direction TB
PacienteE["Paciente\n(CPF único)"]:::entity
ProfissionalE["Profissional\n(CRM/COREN único)"]:::entity
ConsultaE["Consulta\n(data,hora,status,\npatient_id,profissional_id)"]:::entity
ProntuarioE["Prontuário\n(registro pós-consulta)"]:::entity

PacienteE -->|"1_N"| ConsultaE
ProfissionalE -->|"1_N"| ConsultaE
ConsultaE -->|"1_1_ou_1_N"| ProntuarioE
end

%% Notes / ADR-style hints
subgraph "Notas (estado atual vs alvo)"
direction TB
N1["Estado atual: scripts educacionais dispersos\n(Cap 02–09, notebooks)"]:::note
N2["Persistência inicial: .txt / .pickle\n(migrável depois p/ SQLite)"]:::note
N3["Arquitetura alvo: UI → Services → Repos → Storage\n(mesmo sendo monólito local)"]:::note
end

SYS -.->|"contexto"| N1
Persist -.->|"decisão"| N2
Domain -.->|"organização"| N3

%% =========================
%% Click Events (component_mapping)
%% =========================
click CLI1 "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/app_agenda.py"
click CLI1 "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/app_tarefas.py"
click CLIMenu "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 03/menu.py"

click AgendaDomainExample "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/agenda.py"
click Auth "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/login.py"

click TxtStore "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/agenda.txt"
click TxtStore "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/numeros.txt"
click TxtCreator "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/cria_txt.py"

click PickleStore "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/data.pickle"
click PickleStore "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/mi.pickle"
click BinCreator "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/cria_bin.py"
click BinCreatorSimple "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 09/cria_bin_simples.py"

click UtilLib "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 08/biblioteca.py"
click UtilUse "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/Cap 08/chama_biblioteca.py"

click SYS "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/README.md"
click SYS "https://github.com/fgsantosti/algoritmosprogramacao/blob/master/desafio_clinica.txt"

%% =========================
%% Styles
%% =========================
classDef actor fill:#E6E6E6,stroke:#666,stroke-width:1px,color:#111;
classDef system fill:#111827,stroke:#0B1220,stroke-width:1.5px,color:#FFFFFF;
classDef ui fill:#DBEAFE,stroke:#2563EB,stroke-width:1.5px,color:#0B1220;
classDef domain fill:#DCFCE7,stroke:#16A34A,stroke-width:1.5px,color:#052E16;
classDef persistence fill:#FFEDD5,stroke:#F97316,stroke-width:1.5px,color:#431407;
classDef storage fill:#F3F4F6,stroke:#6B7280,stroke-width:1.5px,color:#111827;
classDef external fill:#E5E7EB,stroke:#374151,stroke-width:1.5px,color:#111827,stroke-dasharray: 4 3;
classDef util fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#1F2937;
classDef entity fill:#FEF9C3,stroke:#CA8A04,stroke-width:1.5px,color:#1F2937;
classDef note fill:#FFF7ED,stroke:#9A3412,stroke-width:1px,color:#7C2D12,stroke-dasharray: 3 3;
```
