# albert-labs/albert-python architecture

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

- Interactive diagram: https://gitdiagram.com/albert-labs/albert-python
- Repository: https://github.com/albert-labs/albert-python

## Overview

1. This repository is a Python SDK, not an application server. Its core purpose is to provide a typed, organized client for the Albert Invent platform’s REST-style resources such as projects, inventory, lots, sheets, users, tasks, and many others.

2. The top-level entry point is `src/albert/__init__.py` and `src/albert/client.py`. The `Albert` client is the main façade that application code uses to construct authenticated clients and access resource groups like `client.projects`, `client.inventory`, or `client.lots`.

3. The networking and request lifecycle live under `src/albert/core/`. This layer contains the synchronous and asynchronous session implementations, pagination helpers, shared base classes, logging, and utility code. It is the transport boundary between SDK consumers and the Albert API.

4. Authentication is a dedicated subsystem in `src/albert/core/auth/`. It includes client-credential handling, SSO support, token/listener management, and credentials models. This layer feeds the session layer so all downstream resource calls are authenticated consistently.

5. The SDK splits domain access into two parallel abstractions:
   - `src/albert/resources/` for API-facing resource managers and endpoints
   - `src/albert/collections/` for collection/data models and higher-level entity representations  
   In practice, resources orchestrate HTTP operations while collections define the domain objects and request/response shapes.

6. Most business domains are represented as first-class modules, not generic endpoints. Examples include projects, inventory, notebooks, sheets, tasks, storage locations, substances, hazards, data templates, custom fields, teams, roles, reports, and chats. This suggests the diagram should show many peer resource domains hanging off a shared client core.

7. There is a clear shared-model layer in `src/albert/core/shared/`. It defines common enums, identifiers, base models, patch models, and shared types used across both resource and collection code. This is the main consistency boundary for schema and identifier handling.

8. Utility modules in `src/albert/utils/` provide domain-specific helpers for auth, patching, dataframes, custom fields, inventory, property data, tasks, and worksheets. These are convenience layers above the raw resources, likely used to normalize payloads or simplify common workflows.

9. The repository also includes some specialized subresources that imply richer workflows beyond simple CRUD. Notable examples are smart datasets, worker jobs, report templates, chats, and smart projects. These should be treated as separate architectural nodes because they likely coordinate multiple underlying API calls.

10. Tests mirror the architecture closely. `tests/collections/`, `tests/resources/`, `tests/core/`, and `tests/utils/` validate each layer independently, while `tests/data/` contains fixture artifacts such as a PDF sample. This indicates a layered design with unit tests around each boundary rather than one monolithic integration suite.

11. Documentation is a major part of the repo. The `docs/` tree contains concept pages, authentication, configuration, migration, SSO, examples, and extensive resource/collection references. The architecture of the SDK is therefore intended to be discoverable by generated or maintained docs aligned to the code modules.

12. Tooling and release automation are present but not part of runtime behavior: `pyproject.toml`, `mkdocs.yml`, pre-commit config, GitHub Actions, CircleCI, and release-please config. These support validation, documentation publishing, and package release, but the runtime architecture remains the client/auth/session/resource stack described above.

13. For an architecture diagram, the central flow is: consumer code -> `Albert` client -> auth/session core -> resource layer -> API responses -> collection/shared models/utilities. The main boundary is the SDK-to-platform HTTP edge; everything else is internal organization around domain-specific access patterns.

Main entry points: [`src/albert/resources`](https://github.com/albert-labs/albert-python/tree/main/src/albert/resources) (Resources), [`src/albert/client.py`](https://github.com/albert-labs/albert-python/blob/main/src/albert/client.py) (Albert client), [`src/albert/core/session.py`](https://github.com/albert-labs/albert-python/blob/main/src/albert/core/session.py) (Session core), [`tests`](https://github.com/albert-labs/albert-python/tree/main/tests) (Layered tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src["Source"]
  node_albert_client["Albert client<br/>façade<br/>[client.py]"]
  node_core_auth["Auth core<br/>authentication"]
  node_core_session["Session core<br/>transport<br/>[session.py]"]
  node_core_shared["Shared models<br/>schema primitives"]
  node_core_pagination(("Pagination<br/>paging helper<br/>[pagination.py]"))
  node_resource_layer["Resources<br/>API managers"]
  node_collection_layer["Collections<br/>domain models"]
  node_utils_layer["Utilities<br/>helpers"]
  node_projects["Projects<br/>resource domain<br/>[projects.py]"]
  node_inventory["Inventory<br/>resource domain<br/>[inventory.py]"]
  node_lots["Lots<br/>resource domain<br/>[lots.py]"]
  node_sheets["Sheets<br/>resource domain<br/>[sheets.py]"]
  node_users["Users<br/>resource domain<br/>[users.py]"]
  node_tasks["Tasks<br/>workflow domain<br/>[tasks.py]"]
  node_smart_ds["Smart datasets<br/>specialized workflow<br/>[smart_datasets.py]"]
  node_reports["Reports<br/>resource domain<br/>[reports.py]"]
  node_chats["Chats<br/>resource domain<br/>[chats.py]"]
end

subgraph group_docs["Docs"]
  node_docs_tree["Docs tree<br/>documentation"]
end

subgraph group_tests["Tests"]
  node_tests_layers["Layered tests<br/>verification"]
end

node_albert_client -->|"configures"| node_core_auth
node_albert_client -->|"uses"| node_core_session
node_albert_client -->|"exposes"| node_resource_layer
node_albert_client -->|"returns"| node_collection_layer
node_core_auth -->|"feeds"| node_core_session
node_core_session -->|"serves"| node_resource_layer
node_core_session -->|"applies"| node_core_pagination
node_resource_layer -->|"contains"| node_projects
node_resource_layer -->|"contains"| node_inventory
node_resource_layer -->|"contains"| node_lots
node_resource_layer -->|"contains"| node_sheets
node_resource_layer -->|"contains"| node_users
node_resource_layer -->|"contains"| node_tasks
node_resource_layer -->|"contains"| node_smart_ds
node_resource_layer -->|"contains"| node_reports
node_resource_layer -->|"contains"| node_chats
node_resource_layer -->|"maps to"| node_collection_layer
node_collection_layer -->|"depends on"| node_core_shared
node_utils_layer -->|"reuses"| node_core_shared
node_utils_layer -->|"supports"| node_resource_layer
node_docs_tree -.->|"documents"| node_albert_client
node_docs_tree -.->|"documents"| node_core_auth
node_docs_tree -.->|"documents"| node_resource_layer
node_tests_layers -.->|"validates"| node_collection_layer
node_tests_layers -.->|"validates"| node_resource_layer
node_tests_layers -.->|"validates"| node_core_session
node_tests_layers -.->|"validates"| node_utils_layer

click node_albert_client "https://github.com/albert-labs/albert-python/blob/main/src/albert/client.py"
click node_core_auth "https://github.com/albert-labs/albert-python/tree/main/src/albert/core/auth"
click node_core_session "https://github.com/albert-labs/albert-python/blob/main/src/albert/core/session.py"
click node_core_shared "https://github.com/albert-labs/albert-python/tree/main/src/albert/core/shared"
click node_core_pagination "https://github.com/albert-labs/albert-python/blob/main/src/albert/core/pagination.py"
click node_resource_layer "https://github.com/albert-labs/albert-python/tree/main/src/albert/resources"
click node_collection_layer "https://github.com/albert-labs/albert-python/tree/main/src/albert/collections"
click node_utils_layer "https://github.com/albert-labs/albert-python/tree/main/src/albert/utils"
click node_projects "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/projects.py"
click node_inventory "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/inventory.py"
click node_lots "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/lots.py"
click node_sheets "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/sheets.py"
click node_users "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/users.py"
click node_tasks "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/tasks.py"
click node_smart_ds "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/smart_datasets.py"
click node_reports "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/reports.py"
click node_chats "https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/chats.py"
click node_docs_tree "https://github.com/albert-labs/albert-python/tree/main/docs"
click node_tests_layers "https://github.com/albert-labs/albert-python/tree/main/tests"

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_albert_client,node_core_auth,node_core_session,node_core_shared,node_core_pagination,node_resource_layer,node_collection_layer,node_utils_layer,node_projects,node_inventory,node_lots,node_sheets,node_users,node_tasks,node_smart_ds,node_reports,node_chats toneBlue
class node_docs_tree toneAmber
class node_tests_layers toneMint
```

## Components

### Source

Runtime SDK code under src/albert

- [Albert client](https://github.com/albert-labs/albert-python/blob/main/src/albert/client.py): façade · Main SDK entry point for authenticated client construction and resource access · `src/albert/client.py`
- [Auth core](https://github.com/albert-labs/albert-python/tree/main/src/albert/core/auth): authentication · Client credentials, SSO, token handling, and auth listener management · `src/albert/core/auth`
- [Session core](https://github.com/albert-labs/albert-python/blob/main/src/albert/core/session.py): transport · Synchronous and async request lifecycle and HTTP session boundary · `src/albert/core/session.py`
- [Shared models](https://github.com/albert-labs/albert-python/tree/main/src/albert/core/shared): schema primitives · Common enums, identifiers, base models, patch models, and shared types · `src/albert/core/shared`
- [Pagination](https://github.com/albert-labs/albert-python/blob/main/src/albert/core/pagination.py): paging helper · Shared pagination behavior for API result traversal · `src/albert/core/pagination.py`
- [Resources](https://github.com/albert-labs/albert-python/tree/main/src/albert/resources): API managers · Endpoint managers that orchestrate HTTP operations for platform domains · `src/albert/resources`
- [Collections](https://github.com/albert-labs/albert-python/tree/main/src/albert/collections): domain models · Higher-level collection and entity representations for request and response shapes · `src/albert/collections`
- [Utilities](https://github.com/albert-labs/albert-python/tree/main/src/albert/utils): helpers · Convenience helpers for auth, patching, dataframes, inventory, tasks, and worksheets · `src/albert/utils`
- [Projects](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/projects.py): resource domain · Project access and orchestration · `src/albert/resources/projects.py`
- [Inventory](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/inventory.py): resource domain · Inventory operations and domain workflows · `src/albert/resources/inventory.py`
- [Lots](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/lots.py): resource domain · Lot-centric resource access · `src/albert/resources/lots.py`
- [Sheets](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/sheets.py): resource domain · Sheet operations and related API flows · `src/albert/resources/sheets.py`
- [Users](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/users.py): resource domain · User and identity access · `src/albert/resources/users.py`
- [Tasks](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/tasks.py): workflow domain · Task workflows and coordination helpers · `src/albert/resources/tasks.py`
- [Smart datasets](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/smart_datasets.py): specialized workflow · Dataset-oriented workflow abstraction over multiple API calls · `src/albert/resources/smart_datasets.py`
- [Reports](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/reports.py): resource domain · Report and report-template access · `src/albert/resources/reports.py`
- [Chats](https://github.com/albert-labs/albert-python/blob/main/src/albert/resources/chats.py): resource domain · Chat sessions, folders, flags, and messages access · `src/albert/resources/chats.py`

### Docs

Documentation aligned to SDK modules

- [Docs tree](https://github.com/albert-labs/albert-python/tree/main/docs): documentation · Concepts, authentication, configuration, examples, and resource references · `docs`

### Tests

Layered tests mirroring source architecture

- [Layered tests](https://github.com/albert-labs/albert-python/tree/main/tests): verification · Tests covering collections, resources, core, and utils boundaries · `tests`

## Connections

- Albert client → Auth core: configures · Creates authenticated client sessions
- Albert client → Session core: uses · Routes API calls through the transport layer
- Albert client → Resources: exposes · Publishes domain managers like projects, inventory, and lots
- Albert client → Collections: returns · Hands back typed domain models and collections
- Auth core → Session core: feeds · Supplies credentials and tokens to request sessions
- Session core → Resources: serves · Executes authenticated HTTP operations for resources
- Session core → Pagination: applies · Uses shared pagination while iterating result sets
- Resources → Projects: contains · Project manager endpoint
- Resources → Inventory: contains · Inventory manager endpoint
- Resources → Lots: contains · Lot manager endpoint
- Resources → Sheets: contains · Sheet manager endpoint
- Resources → Users: contains · User manager endpoint
- Resources → Tasks: contains · Task workflows and operations
- Resources → Smart datasets: contains · Specialized smart dataset workflow
- Resources → Reports: contains · Reports and templates
- Resources → Chats: contains · Chat domain operations
- Resources → Collections: maps to · Converts API payloads to collection entities
- Collections → Shared models: depends on · Shares base models, enums, identifiers, and types
- Utilities → Shared models: reuses · Applies shared patching and identifier conventions
- Utilities → Resources: supports · Convenience helpers above raw resource calls
- Docs tree → Albert client: documents · Explains client entry points and usage
- Docs tree → Auth core: documents · Covers authentication and SSO
- Docs tree → Resources: documents · Provides per-resource and per-collection references
- Layered tests → Collections: validates · Collection-level unit tests
- Layered tests → Resources: validates · Resource-level unit tests
- Layered tests → Session core: validates · Core transport and auth tests
- Layered tests → Utilities: validates · Utility helpers and patch behavior
