# eytanohana/fast-pager architecture

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

- Interactive diagram: https://gitdiagram.com/eytanohana/fast-pager
- Repository: https://github.com/eytanohana/fast-pager

## Overview

fast-pager is a FastAPI query-parameter and database-query compilation library. The main workflow starts when a route registers FilterDepends: model metadata and configuration define the exposed filter surface; FastAPI validates request parameters; FilterQuery parses them into a backend-neutral AST; a backend compiler produces a query for the application’s database. Pagination can additionally return a Page envelope. The graph includes the documented MongoDB and SQLAlchemy backends. Some internal relationships are evidenced only by the source index; conformance is included as a substantial module, but its runtime role is unclear from the excerpts.

Main entry points: [`src/fast_pager/query.py`](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/query.py) (FilterQuery), [`src/fast_pager/dependency.py`](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/dependency.py) (FastAPI dependency), [`src/fast_pager/params.py`](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/params.py) (Query parameters), [`src/fast_pager/introspection.py`](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/introspection.py) (Model introspection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API configuration"]
  node_dependency["FastAPI dependency<br/>[dependency.py]"]
  node_config["Filter config<br/>[config.py]"]
  node_filterset["FilterSet allow-list<br/>[filterset.py]"]
  node_field_control["Field controls<br/>[filterable.py]"]
end

subgraph group_request["Request modeling"]
  node_introspection["Model introspection<br/>[introspection.py]"]
  node_operators["Operator registry<br/>[operators.py]"]
  node_param_model["Query parameters<br/>[params.py]"]
end

subgraph group_query["Query representation"]
  node_filter_query["FilterQuery<br/>[query.py]"]
  node_ast["Filter AST<br/>[ast.py]"]
  node_pagination["Page envelope<br/>[pagination.py]"]
end

subgraph group_backends["Backend compilation"]
  node_compiler_contract["Compiler contract<br/>[base.py]"]
  node_mongo["Mongo compiler<br/>[mongo.py]"]
  node_sqlalchemy["SQLAlchemy compiler<br/>[sqlalchemy.py]"]
  node_conformance["Conformance module<br/>[conformance.py]"]
end

node_route_user(("Route author"))
node_database[("Application database")]

node_route_user -->|"registers filters"| node_dependency
node_dependency -->|"uses settings"| node_config
node_dependency -->|"accepts filter set"| node_filterset
node_dependency -->|"builds parameters"| node_param_model
node_dependency -->|"provides query"| node_filter_query
node_param_model -->|"derives fields"| node_introspection
node_param_model -->|"resolves operators"| node_operators
node_introspection -->|"reads metadata"| node_field_control
node_introspection -->|"classifies types"| node_operators
node_filterset -->|"selects fields"| node_introspection
node_filterset -->|"defines surface"| node_param_model
node_filter_query -->|"parses validated values"| node_param_model
node_filter_query -->|"builds AST"| node_ast
node_filter_query -->|"compiles Mongo query"| node_mongo
node_filter_query -->|"applies SQL query"| node_sqlalchemy
node_filter_query -->|"paginates collection"| node_pagination
node_mongo -->|"implements contract"| node_compiler_contract
node_sqlalchemy -->|"implements contract"| node_compiler_contract
node_mongo -->|"compiles AST"| node_ast
node_sqlalchemy -->|"compiles AST"| node_ast
node_route_user -->|"executes compiled query"| node_database
node_filter_query -->|"paginates collection"| node_database

click node_dependency "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/dependency.py"
click node_config "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/config.py"
click node_filterset "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/filterset.py"
click node_field_control "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/filterable.py"
click node_introspection "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/introspection.py"
click node_operators "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/operators.py"
click node_param_model "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/params.py"
click node_filter_query "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/query.py"
click node_ast "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/ast.py"
click node_pagination "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/pagination.py"
click node_compiler_contract "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/base.py"
click node_mongo "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/mongo.py"
click node_sqlalchemy "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/sqlalchemy.py"
click node_conformance "https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/conformance.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_dependency,node_config,node_filterset,node_field_control toneBlue
class node_introspection,node_operators,node_param_model,node_database toneAmber
class node_filter_query,node_ast,node_pagination,node_route_user toneMint
class node_compiler_contract,node_mongo,node_sqlalchemy,node_conformance toneRose
```

## Components

### API configuration

- [FastAPI dependency](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/dependency.py): `src/fast_pager/dependency.py`
- [Filter config](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/config.py): `src/fast_pager/config.py`
- [FilterSet allow-list](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/filterset.py): `src/fast_pager/filterset.py`
- [Field controls](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/filterable.py): `src/fast_pager/filterable.py`

### Request modeling

- [Model introspection](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/introspection.py): `src/fast_pager/introspection.py`
- [Operator registry](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/operators.py): `src/fast_pager/operators.py`
- [Query parameters](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/params.py): `src/fast_pager/params.py`

### Query representation

- [FilterQuery](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/query.py): `src/fast_pager/query.py`
- [Filter AST](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/ast.py): `src/fast_pager/ast.py`
- [Page envelope](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/pagination.py): `src/fast_pager/pagination.py`

### Backend compilation

- [Compiler contract](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/base.py): `src/fast_pager/backends/base.py`
- [Mongo compiler](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/mongo.py): `src/fast_pager/backends/mongo.py`
- [SQLAlchemy compiler](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/backends/sqlalchemy.py): `src/fast_pager/backends/sqlalchemy.py`
- [Conformance module](https://github.com/eytanohana/fast-pager/blob/main/src/fast_pager/conformance.py): `src/fast_pager/conformance.py`

### Other components

- **Route author**
- **Application database**

## Connections

- Route author → FastAPI dependency: registers filters (evidence: `README.md`)
- FastAPI dependency → Filter config: uses settings (evidence: `src/fast_pager/dependency.py`)
- FastAPI dependency → FilterSet allow-list: accepts filter set (evidence: `src/fast_pager/dependency.py`)
- FastAPI dependency → Query parameters: builds parameters (evidence: `src/fast_pager/dependency.py`)
- FastAPI dependency → FilterQuery: provides query (evidence: `src/fast_pager/dependency.py`)
- Query parameters → Model introspection: derives fields (evidence: `src/fast_pager/params.py`)
- Query parameters → Operator registry: resolves operators (evidence: `src/fast_pager/params.py`)
- Model introspection → Field controls: reads metadata (evidence: `src/fast_pager/introspection.py`)
- Model introspection → Operator registry: classifies types (evidence: `src/fast_pager/introspection.py`)
- FilterSet allow-list → Model introspection: selects fields (evidence: `src/fast_pager/filterset.py`)
- FilterSet allow-list → Query parameters: defines surface (evidence: `src/fast_pager/filterset.py`)
- FilterQuery → Query parameters: parses validated values (evidence: `src/fast_pager/query.py`)
- FilterQuery → Filter AST: builds AST (evidence: `src/fast_pager/query.py`)
- FilterQuery → Mongo compiler: compiles Mongo query (evidence: `src/fast_pager/query.py`)
- FilterQuery → SQLAlchemy compiler: applies SQL query (evidence: `README.md`)
- FilterQuery → Page envelope: paginates collection (evidence: `src/fast_pager/query.py`)
- Mongo compiler → Compiler contract: implements contract (evidence: `src/fast_pager/backends/mongo.py`)
- SQLAlchemy compiler → Compiler contract: implements contract (evidence: `src/fast_pager/backends/sqlalchemy.py`)
- Mongo compiler → Filter AST: compiles AST (evidence: `src/fast_pager/backends/mongo.py`)
- SQLAlchemy compiler → Filter AST: compiles AST (evidence: `src/fast_pager/backends/sqlalchemy.py`)
- Route author → Application database: executes compiled query (evidence: `README.md`)
- FilterQuery → Application database: paginates collection (evidence: `README.md`)
