# eduardoarsocca/integracao_natura architecture

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

- Interactive diagram: https://gitdiagram.com/eduardoarsocca/integracao_natura
- Repository: https://github.com/eduardoarsocca/integracao_natura

## Overview

This is a clinical-study integration service that synchronizes REDCap event records into PoloTrial. A webhook receives an event, dispatch selects a stage-specific handler, and that handler reads REDCap data and creates or updates participants, visits, procedures, executors, or participant status in PoloTrial. The repository also provides a CLI and reusable synchronization helpers. The main routing and several handlers are excerpted; relationships based only on the source index are marked dashed where invocation is not shown.

Main entry points: [`src/integracao/dispatch.py`](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/dispatch.py) (Event dispatcher), [`src/integracao/redcap_client.py`](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/redcap_client.py) (REDCap client), [`src/integracao/events/generic_visit.py`](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/generic_visit.py) (Generic visits), [`src/integracao/polotrial_client.py`](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/polotrial_client.py) (PoloTrial client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Event ingress"]
  node_webhook["Webhook receiver<br/>[webhook.py]"]
  node_cli["CLI runner<br/>[cli.py]"]
  node_dispatch["Event dispatcher<br/>[dispatch.py]"]
end

subgraph group_workflow["Synchronization workflows"]
  node_v1["V1 screening<br/>[v1_screening.py]"]
  node_v2["V2 randomization<br/>[v2_randomizacao.py]"]
  node_generic["Generic visits<br/>[generic_visit.py]"]
  node_status["Status updates"]
  node_visit_catalog["Visit catalog<br/>[visits_catalog.py]"]
end

subgraph group_core["Sync core"]
  node_sync["Sync engine<br/>[sync_engine.py]"]
  node_utils["Date utilities<br/>[utils.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_logging["Logging setup<br/>[logging_conf.py]"]
end

subgraph group_adapters["Service adapters"]
  node_redcap_client["REDCap client<br/>[redcap_client.py]"]
  node_polotrial_client["PoloTrial client"]
end

subgraph group_mapping["Domain mappings"]
  node_mappings["Field and procedure maps"]
  node_event_names["REDCap event names"]
end

node_redcap_actor(("REDCap event"))
node_redcap_service{{"REDCap API"}}
node_polotrial_service{{"PoloTrial API"}}

node_redcap_actor -.->|"sends event"| node_webhook
node_webhook -.->|"routes event"| node_dispatch
node_cli -.->|"dispatches event"| node_dispatch
node_dispatch -->|"dispatches V1"| node_v1
node_dispatch -->|"dispatches V2"| node_v2
node_dispatch -->|"dispatches visit"| node_generic
node_dispatch -->|"dispatches status"| node_status
node_dispatch -->|"checks events"| node_visit_catalog
node_generic -.->|"uses visit config"| node_visit_catalog
node_v1 -->|"exports records"| node_redcap_client
node_v1 -->|"syncs screening"| node_polotrial_client
node_v1 -->|"matches procedures"| node_mappings
node_v2 -->|"exports records"| node_redcap_client
node_v2 -->|"syncs randomization"| node_polotrial_client
node_v2 -->|"maps procedures"| node_mappings
node_generic -->|"exports visit data"| node_redcap_client
node_generic -->|"syncs visit"| node_polotrial_client
node_generic -->|"calls sync helpers"| node_sync
node_generic -.->|"resolves visit name"| node_mappings
node_status -->|"exports status"| node_redcap_client
node_status -->|"updates status"| node_polotrial_client
node_status -->|"maps site and status"| node_mappings
node_sync -->|"reads record"| node_redcap_client
node_sync -->|"updates visit"| node_polotrial_client
node_sync -->|"uses site codes"| node_mappings
node_utils -.->|"uses client type"| node_redcap_client
node_redcap_client -->|"calls API"| node_redcap_service
node_polotrial_client -->|"calls API"| node_polotrial_service
node_webhook -.->|"loads settings"| node_config
node_webhook -.->|"configures logs"| node_logging
node_dispatch -.->|"uses event names"| node_event_names

click node_webhook "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/webhook.py"
click node_cli "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/cli.py"
click node_dispatch "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/dispatch.py"
click node_v1 "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/v1_screening.py"
click node_v2 "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/v2_randomizacao.py"
click node_generic "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/generic_visit.py"
click node_status "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/status_atualization.py"
click node_visit_catalog "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/visits_catalog.py"
click node_sync "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/sync_engine.py"
click node_utils "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/utils.py"
click node_redcap_client "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/redcap_client.py"
click node_polotrial_client "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/polotrial_client.py"
click node_mappings "https://github.com/eduardoarsocca/integracao_natura/tree/main/src/integracao/mappings"
click node_config "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/config.py"
click node_logging "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/logging_conf.py"
click node_event_names "https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/redcap_unique_event_names.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webhook,node_cli,node_dispatch toneBlue
class node_v1,node_v2,node_generic,node_status,node_visit_catalog toneAmber
class node_sync,node_utils,node_config,node_logging,node_redcap_service,node_polotrial_service toneMint
class node_redcap_client,node_polotrial_client toneRose
class node_mappings,node_event_names,node_redcap_actor toneIndigo
```

## Components

### Event ingress

- [Webhook receiver](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/webhook.py): `src/integracao/webhook.py`
- [CLI runner](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/cli.py): `src/integracao/cli.py`
- [Event dispatcher](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/dispatch.py): `src/integracao/dispatch.py`

### Synchronization workflows

- [V1 screening](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/v1_screening.py): `src/integracao/events/v1_screening.py`
- [V2 randomization](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/v2_randomizacao.py): `src/integracao/events/v2_randomizacao.py`
- [Generic visits](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/generic_visit.py): `src/integracao/events/generic_visit.py`
- [Status updates](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/events/status_atualization.py): `src/integracao/events/status_atualization.py`
- [Visit catalog](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/visits_catalog.py): `src/integracao/visits_catalog.py`

### Sync core

- [Sync engine](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/sync_engine.py): `src/integracao/sync_engine.py`
- [Date utilities](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/utils.py): `src/integracao/utils.py`
- [Runtime configuration](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/config.py): `src/integracao/config.py`
- [Logging setup](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/logging_conf.py): `src/integracao/logging_conf.py`

### Service adapters

- [REDCap client](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/redcap_client.py): `src/integracao/redcap_client.py`
- [PoloTrial client](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/polotrial_client.py): `src/integracao/polotrial_client.py`

### Domain mappings

- [Field and procedure maps](https://github.com/eduardoarsocca/integracao_natura/tree/main/src/integracao/mappings): `src/integracao/mappings`
- [REDCap event names](https://github.com/eduardoarsocca/integracao_natura/blob/main/src/integracao/redcap_unique_event_names.py): `src/integracao/redcap_unique_event_names.py`

### Other components

- **REDCap event**
- **REDCap API**
- **PoloTrial API**

## Connections

- REDCap event → Webhook receiver: sends event
- Webhook receiver → Event dispatcher: routes event (evidence: `src/integracao/webhook.py`)
- CLI runner → Event dispatcher: dispatches event (evidence: `src/integracao/cli.py`)
- Event dispatcher → V1 screening: dispatches V1 (evidence: `src/integracao/dispatch.py`)
- Event dispatcher → V2 randomization: dispatches V2 (evidence: `src/integracao/dispatch.py`)
- Event dispatcher → Generic visits: dispatches visit (evidence: `src/integracao/dispatch.py`)
- Event dispatcher → Status updates: dispatches status (evidence: `src/integracao/dispatch.py`)
- Event dispatcher → Visit catalog: checks events (evidence: `src/integracao/dispatch.py`)
- Generic visits → Visit catalog: uses visit config (evidence: `src/integracao/events/generic_visit.py`)
- V1 screening → REDCap client: exports records (evidence: `src/integracao/events/v1_screening.py`)
- V1 screening → PoloTrial client: syncs screening (evidence: `src/integracao/events/v1_screening.py`)
- V1 screening → Field and procedure maps: matches procedures (evidence: `src/integracao/events/v1_screening.py`)
- V2 randomization → REDCap client: exports records (evidence: `src/integracao/events/v2_randomizacao.py`)
- V2 randomization → PoloTrial client: syncs randomization (evidence: `src/integracao/events/v2_randomizacao.py`)
- V2 randomization → Field and procedure maps: maps procedures (evidence: `src/integracao/events/v2_randomizacao.py`)
- Generic visits → REDCap client: exports visit data (evidence: `src/integracao/events/generic_visit.py`)
- Generic visits → PoloTrial client: syncs visit (evidence: `src/integracao/events/generic_visit.py`)
- Generic visits → Sync engine: calls sync helpers (evidence: `src/integracao/events/generic_visit.py`)
- Generic visits → Field and procedure maps: resolves visit name (evidence: `src/integracao/events/generic_visit.py`)
- Status updates → REDCap client: exports status (evidence: `src/integracao/events/status_atualization.py`)
- Status updates → PoloTrial client: updates status (evidence: `src/integracao/events/status_atualization.py`)
- Status updates → Field and procedure maps: maps site and status (evidence: `src/integracao/events/status_atualization.py`)
- Sync engine → REDCap client: reads record (evidence: `src/integracao/sync_engine.py`)
- Sync engine → PoloTrial client: updates visit (evidence: `src/integracao/sync_engine.py`)
- Sync engine → Field and procedure maps: uses site codes (evidence: `src/integracao/sync_engine.py`)
- Date utilities → REDCap client: uses client type (evidence: `src/integracao/utils.py`)
- REDCap client → REDCap API: calls API (evidence: `src/integracao/redcap_client.py`)
- PoloTrial client → PoloTrial API: calls API (evidence: `src/integracao/polotrial_client.py`)
- Webhook receiver → Runtime configuration: loads settings (evidence: `src/integracao/webhook.py`)
- Webhook receiver → Logging setup: configures logs (evidence: `src/integracao/webhook.py`)
- Event dispatcher → REDCap event names: uses event names
