# smorokin/fassung architecture

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

- Interactive diagram: https://gitdiagram.com/smorokin/fassung
- Repository: https://github.com/smorokin/fassung

## Overview

Fassung is an async Python interface to PostgreSQL that combines asyncpg, PEP 750 template strings, and Pydantic mapping. A caller obtains a pooled connection, opens a transaction, submits a composable template query, and receives typed results or streams rows through a cursor. Connections assemble templates into parameterized SQL before delegating database operations; typed result parsing is a shared internal layer. The README also describes nested query composition and listener support. Connection internals are partially excerpted, so uncertain wiring is omitted.

Main entry points: [`src/fassung/connection.py`](https://github.com/smorokin/fassung/blob/main/src/fassung/connection.py) (Connection), [`src/fassung/pool.py`](https://github.com/smorokin/fassung/blob/main/src/fassung/pool.py) (Pool), [`src/fassung/type_parser.py`](https://github.com/smorokin/fassung/blob/main/src/fassung/type_parser.py) (Type Parser), [`src/fassung/cursor.py`](https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py) (Cursor Factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Connection Access"]
  node_pool["Pool<br/>[pool.py]"]
  node_connection["Connection<br/>[connection.py]"]
  node_transaction["Transaction<br/>[connection.py]"]
  node_exceptions["Errors<br/>[exceptions.py]"]
end

subgraph group_queries["Query Execution"]
  node_assembler["Query Assembler<br/>[query_assembler.py]"]
  node_asyncpg["asyncpg"]
  node_cursor_factory["Cursor Factory<br/>[cursor.py]"]
  node_cursor["Cursor<br/>[cursor.py]"]
  node_cursor_iterator["Cursor Iterator<br/>[cursor.py]"]
end

subgraph group_mapping["Typed Results"]
  node_parser["Type Parser<br/>[type_parser.py]"]
  node_mapped_record["Mapped Record<br/>[record.py]"]
  node_pydantic["Pydantic"]
end

subgraph group_events["Database Events"]
  node_listeners["Listener API<br/>[types.py]"]
end

node_caller(("Application"))
node_postgres[("PostgreSQL")]

node_caller -->|"creates"| node_pool
node_caller -->|"acquires"| node_pool
node_pool -->|"creates pool"| node_asyncpg
node_pool -->|"yields"| node_connection
node_caller -->|"runs queries"| node_connection
node_connection -->|"starts"| node_transaction
node_transaction -->|"proxies queries"| node_connection
node_connection -->|"assembles templates"| node_assembler
node_connection -->|"executes SQL"| node_asyncpg
node_asyncpg -->|"queries"| node_postgres
node_connection -->|"creates cursor"| node_cursor_factory
node_cursor_factory -->|"wraps cursor factory"| node_asyncpg
node_cursor_factory -->|"awaits into"| node_cursor
node_cursor_factory -->|"iterates as"| node_cursor_iterator
node_cursor -->|"parses rows"| node_parser
node_cursor_iterator -->|"parses rows"| node_parser
node_connection -->|"parses results"| node_parser
node_parser -->|"validates with"| node_pydantic
node_pool -->|"configures records"| node_mapped_record
node_connection -->|"accepts callbacks"| node_listeners
node_connection -->|"parses payloads"| node_parser
node_connection -->|"registers listeners"| node_asyncpg
node_connection -->|"removes listeners"| node_asyncpg
node_connection -->|"raises on closed transaction"| node_exceptions
node_assembler -->|"rejects plain strings"| node_exceptions

click node_pool "https://github.com/smorokin/fassung/blob/main/src/fassung/pool.py"
click node_connection "https://github.com/smorokin/fassung/blob/main/src/fassung/connection.py"
click node_transaction "https://github.com/smorokin/fassung/blob/main/src/fassung/connection.py"
click node_assembler "https://github.com/smorokin/fassung/blob/main/src/fassung/query_assembler.py"
click node_cursor_factory "https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py"
click node_cursor "https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py"
click node_cursor_iterator "https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py"
click node_parser "https://github.com/smorokin/fassung/blob/main/src/fassung/type_parser.py"
click node_mapped_record "https://github.com/smorokin/fassung/blob/main/src/fassung/record.py"
click node_listeners "https://github.com/smorokin/fassung/blob/main/src/fassung/types.py"
click node_exceptions "https://github.com/smorokin/fassung/blob/main/src/fassung/exceptions.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_pool,node_connection,node_transaction,node_exceptions toneBlue
class node_assembler,node_asyncpg,node_cursor_factory,node_cursor,node_cursor_iterator,node_postgres toneAmber
class node_parser,node_mapped_record,node_pydantic toneMint
class node_listeners toneRose
class node_caller toneIndigo
```

## Components

### Connection Access

- [Pool](https://github.com/smorokin/fassung/blob/main/src/fassung/pool.py): `src/fassung/pool.py`
- [Connection](https://github.com/smorokin/fassung/blob/main/src/fassung/connection.py): `src/fassung/connection.py`
- [Transaction](https://github.com/smorokin/fassung/blob/main/src/fassung/connection.py): `src/fassung/connection.py`
- [Errors](https://github.com/smorokin/fassung/blob/main/src/fassung/exceptions.py): `src/fassung/exceptions.py`

### Query Execution

- [Query Assembler](https://github.com/smorokin/fassung/blob/main/src/fassung/query_assembler.py): `src/fassung/query_assembler.py`
- **asyncpg**
- [Cursor Factory](https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py): `src/fassung/cursor.py`
- [Cursor](https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py): `src/fassung/cursor.py`
- [Cursor Iterator](https://github.com/smorokin/fassung/blob/main/src/fassung/cursor.py): `src/fassung/cursor.py`

### Typed Results

- [Type Parser](https://github.com/smorokin/fassung/blob/main/src/fassung/type_parser.py): `src/fassung/type_parser.py`
- [Mapped Record](https://github.com/smorokin/fassung/blob/main/src/fassung/record.py): `src/fassung/record.py`
- **Pydantic**

### Database Events

- [Listener API](https://github.com/smorokin/fassung/blob/main/src/fassung/types.py): `src/fassung/types.py`

### Other components

- **Application**
- **PostgreSQL**

## Connections

- Application → Pool: creates
- Application → Pool: acquires
- Pool → asyncpg: creates pool
- Pool → Connection: yields
- Application → Connection: runs queries
- Connection → Transaction: starts
- Transaction → Connection: proxies queries
- Connection → Query Assembler: assembles templates
- Connection → asyncpg: executes SQL
- asyncpg → PostgreSQL: queries
- Connection → Cursor Factory: creates cursor
- Cursor Factory → asyncpg: wraps cursor factory
- Cursor Factory → Cursor: awaits into
- Cursor Factory → Cursor Iterator: iterates as
- Cursor → Type Parser: parses rows
- Cursor Iterator → Type Parser: parses rows
- Connection → Type Parser: parses results
- Type Parser → Pydantic: validates with
- Pool → Mapped Record: configures records
- Connection → Listener API: accepts callbacks
- Connection → Type Parser: parses payloads
- Connection → asyncpg: registers listeners
- Connection → asyncpg: removes listeners
- Connection → Errors: raises on closed transaction
- Query Assembler → Errors: rejects plain strings