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

# Architecture

> How EncodeBox layers, IR compilation, and connectors fit together.

EncodeBox is a semantic layer for healthcare analytics on FDA Sentinel CDM v8.2.2. It generates SQL at query time rather than materializing intermediate tables.

## Design principles

<AccordionGroup>
  <Accordion title="Native Sentinel CDM support">
    YAML connectors map data to FDA Sentinel CDM v8.2.2 table structures with standardized code types (`"10"` ICD-10, `"C4"` CPT, `"ND"` NDC).
  </Accordion>

  <Accordion title="On-the-fly transformation">
    SQL is generated dynamically at query time and runs directly on raw data — no intermediate table management.
  </Accordion>

  <Accordion title="Unified composable API">
    Three interoperable layers: `Table`/`Column` → `EventFrame` → `Cohort`. Shared IR and one compiler to SQLAlchemy. Lazy until `.to_df()` / `.to_sql()` / `.attrition()`.
  </Accordion>

  <Accordion title="Database agnostic">
    Single API across PostgreSQL, Redshift, Snowflake, BigQuery, and MySQL. Dialect-specific SQL is handled internally.
  </Accordion>
</AccordionGroup>

## Layers

```text theme={null}
Layer 2  Cohort          .entry() .include() .exclude() .attrition()
Layer 1  EventFrame      .matching() .occurring() .first_per_patient()
Layer 0  Table / Column  dx.code.startswith("E11") & …
         IR (_internal/ir) → compiler → sqlalchemy.Select
```

Preferred path: YAML connector → `Database` → author at Layer 0/1/2 → shared IR → one compiler → SQLAlchemy → DataFrame.

## Core components

| Component        | Location                  | Role                                 |
| ---------------- | ------------------------- | ------------------------------------ |
| Connector system | `encodebox/connectors/`   | YAML → Pydantic models → registry    |
| Database         | `encodebox/database.py`   | Bound connector + domain accessors   |
| EventFrame       | `encodebox/frame/`        | Layer 1 verbs                        |
| Cohort           | `encodebox/cohort/`       | Layer 2 study definition + attrition |
| IR / compiler    | `encodebox/_internal/ir/` | Sole SQLAlchemy compilation path     |
| Legacy shims     | `encodebox/_compat.py`    | Deprecation wrappers for old helpers |

## Consecutive gaps

`EventFrame.occurring(gap_days=N)` uses `lead()` over ordered distinct dates — **not** span (`max − min`). See [Which API?](/which-api) and [Migration](/migration).

## Transparent SQL

All generated SQL is inspectable via `.to_sql()` and `.explain()` before you call `.to_df()`.