> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmed.med.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitetura

> Visão geral da arquitetura do NextMed Admin Service, camadas, módulos e integrações.

O Admin Service é uma API REST em Node.js (Express) que centraliza a gestão administrativa da plataforma NextMed. Esta página descreve a estrutura de alto nível, os módulos e como as requisições fluem no sistema.

## Visão geral

O serviço expõe endpoints REST, persiste dados em PostgreSQL via TypeORM, pode ser registrado no Eureka para descoberta de serviços e publica eventos em RabbitMQ. Em ambientes com gateway, o tráfego chega ao Admin Service através do gateway; em desenvolvimento, o cliente pode falar direto com o serviço na porta 8081.

```mermaid theme={"system"}
flowchart TB
  subgraph clients["Clientes"]
    Web["Web / Apps"]
    Gateway["Gateway (opcional)"]
  end

  subgraph admin["Admin Service :8081"]
    Express["Express"]
    Routes["Routes"]
    Controllers["Controllers"]
    Services["Services"]
    Repos["Repositories"]
    Express --> Routes --> Controllers --> Services --> Repos
  end

  subgraph infra["Infraestrutura"]
    DB[(PostgreSQL)]
    MQ[RabbitMQ]
    Eureka[Eureka]
  end

  Web --> Gateway
  Gateway --> Express
  Web -.->|desenvolvimento| Express
  Repos --> DB
  admin --> MQ
  admin --> Eureka
```

<Info>
  Em produção, o gateway (ex.: porta 8080) encaminha requisições para o Admin Service e adiciona o prefixo `/admin-service` na maioria dos paths. O path `/protocols` é exposto sem prefixo.
</Info>

## Camadas da aplicação

| Camada             | Responsabilidade                                                                 |
| ------------------ | -------------------------------------------------------------------------------- |
| **HTTP (Express)** | Rotas, middlewares (CORS, JSON, logger), Swagger/OpenAPI.                        |
| **Controllers**    | Recebem request, validam entrada, chamam serviços e devolvem response.           |
| **Services**       | Regras de negócio, orquestração, chamadas a repositórios e integrações.          |
| **Repositories**   | Acesso a dados (TypeORM), abstração sobre o banco.                               |
| **Infra**          | TypeORM (PostgreSQL), RabbitMQ, Eureka, serviços externos (ex.: CNPJ, Firebase). |

```mermaid theme={"system"}
flowchart LR
  subgraph app["Admin Service"]
    direction TB
    A[HTTP / Routes] --> B[Controllers]
    B --> C[Services]
    C --> D[Repositories]
  end
  D --> E[(TypeORM / PostgreSQL)]
  C --> F[RabbitMQ]
  C --> G[Eureka]
  C --> H[Serviços externos]
```

## Módulos

O código está organizado por domínio. Cada módulo agrupa rotas, controllers, serviços e repositórios daquele contexto.

```mermaid theme={"system"}
flowchart TB
  subgraph modules["Módulos de domínio"]
    User["User\nusuários, perfis, auth"]
    Institution["Institution\ninstituições, unidades"]
    Service["Service\nserviços, tipos, preços"]
    Specialty["Specialty\nespecialidades"]
    Protocol["Protocol\nprotocolos, formulários, perguntas"]
    Notification["Notification\nnotificações, cron"]
  end

  subgraph shared["Compartilhado"]
    Infra["Infra (HTTP, TypeORM, messaging)"]
    Errors["Errors / middlewares"]
  end

  User & Institution & Service & Specialty & Protocol & Notification --> Infra
  User & Institution & Service & Protocol --> Errors
```

| Módulo           | Descrição                                                                             |
| ---------------- | ------------------------------------------------------------------------------------- |
| **User**         | Usuários (admin, médico, paciente), perfis, aprovação, autenticação (Firebase, etc.). |
| **Institution**  | Instituições de saúde, unidades (locais), vínculo com usuários e coordenadores.       |
| **Service**      | Serviços, tipos de serviço, histórico de preços, upload de arquivos.                  |
| **Specialty**    | Especialidades médicas utilizadas pelos médicos.                                      |
| **Protocol**     | Protocolos clínicos, versões de formulário, perguntas, opções e faixas de pontuação.  |
| **Notification** | Notificações e jobs agendados (cron).                                                 |

## Fluxo de uma requisição

Exemplo simplificado: cliente chama um endpoint do Admin Service (com ou sem gateway).

```mermaid theme={"system"}
sequenceDiagram
  participant C as Cliente
  participant G as Gateway (opcional)
  participant E as Express
  participant Ctrl as Controller
  participant Svc as Service
  participant Repo as Repository
  participant DB as PostgreSQL

  C->>G: HTTP Request (ex: GET /admin-service/users)
  G->>E: Request (proxy)
  E->>Ctrl: Route handler
  Ctrl->>Svc: listUsers()
  Svc->>Repo: find()
  Repo->>DB: SELECT
  DB-->>Repo: rows
  Repo-->>Svc: entities
  Svc-->>Ctrl: DTOs
  Ctrl-->>E: JSON response
  E-->>G: Response
  G-->>C: Response
```

<Tip>
  O Swagger/OpenAPI está disponível em `/api-docs` quando o serviço está rodando, e a documentação Mintlify gera as páginas da [API Reference](/api-reference) a partir do `openapi.json`.
</Tip>

## Integrações

* **PostgreSQL** — Persistência principal via TypeORM (entidades, migrations, repositórios).
* **Eureka** — Registro e descoberta do serviço em ambientes que usam Netflix Eureka.
* **RabbitMQ** — Publicação de mensagens/eventos para outros serviços.
* **Serviços externos** — Ex.: validação de CNPJ, autenticação (Firebase), conforme configuração do projeto.

<Warning>
  Em produção, credenciais de banco, filas e serviços externos devem vir de variáveis de ambiente ou de um provedor de segredos, nunca fixas no código.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Introdução" icon="info" href="/introduction">
    Recursos da API e base URLs.
  </Card>

  <Card title="API Reference" icon="book-open" href="/api-reference">
    Endpoints, parâmetros e schemas.
  </Card>
</CardGroup>