# kuaterpillar/lbc architecture

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

- Interactive diagram: https://gitdiagram.com/kuaterpillar/lbc
- Repository: https://github.com/kuaterpillar/lbc

## Overview

1. **Overall shape**
   - This repository is a Python 3.9+ package named `lbc`, an unofficial client for the Leboncoin marketplace.
   - The core architectural boundary is between the public Python API (`lbc.Client`, models, enums) and the remote Leboncoin HTTP API it talks to.

2. **Primary runtime path**
   - The main data flow is: user code calls `lbc.Client` → request-building/session logic in `lbc/mixin/*` → HTTP calls to Leboncoin → JSON response parsing into typed models in `lbc/model/*`.
   - The README examples and `examples/` folder show the intended usage pattern: search ads, fetch a single ad, fetch user info, and optionally route traffic through a proxy.

3. **Client composition**
   - `lbc/client.py` is the top-level facade that likely composes the mixins and exposes the stable API.
   - The package is organized around mixins rather than a deep class hierarchy, which keeps search, ad lookup, user lookup, and session/proxy concerns separated but available through one client object.

4. **Network/session boundary**
   - `lbc/mixin/session.py` is the transport boundary: it is where HTTP session management, headers, proxy wiring, and request execution are centralized.
   - `lbc/model/proxy.py` and the README’s `Proxy` examples show that proxy configuration is a first-class concern, not an afterthought.
   - The README’s 403/Datadome note indicates the client is designed to operate against an anti-bot-protected external service, so request frequency and proxy quality materially affect behavior.

5. **Search subsystem**
   - `lbc/mixin/search.py` handles the core query-building logic for Leboncoin search URLs and parameterized searches.
   - Search inputs can come from structured arguments (`text`, `category`, `locations`, ranges like `price` and `square`) or a full Leboncoin URL, with URL input overriding other filters.
   - This is the highest-volume path in the library and is the main source of result lists returned to callers.

6. **Ad and user lookup subsystems**
   - `lbc/mixin/ad.py` and `lbc/mixin/user.py` represent secondary read APIs that retrieve a single ad or user profile/metadata.
   - These paths likely share the same session layer and response-to-model conversion pipeline as search, but expose narrower resource-oriented operations.

7. **Data model layer**
   - `lbc/model/*` contains the typed domain objects used by the client: ads, cities, searches, users, proxies, and enums.
   - The enums in `lbc/model/enums.py` capture Leboncoin’s categorical values such as sort order, ad type, owner type, and categories, making the public API more stable than passing raw strings everywhere.
   - `City`, `Region`, and `Department` show that geography is a key domain concept in the search model.

8. **Utility and configuration support**
   - `lbc/utils.py` and `lbc/dotenv.py` provide shared helpers and environment loading/configuration support.
   - The presence of `.env.example`, `data/bot_config.json`, and other JSON files suggests the project supports both library use and local operational tooling with externalized settings.

9. **Generated/reference data**
   - `utils/generate_enum_*` scripts indicate some model enums or lookup tables are generated from source data, reducing manual maintenance for regions, departments, and categories.
   - The `data/` directory contains persisted JSON artifacts such as searches and seen ads, which appear to support tracking, caching, or monitoring workflows rather than the core library API.

10. **Operational tools and automation**
   - `monitor.py`, `market_analyzer.py`, `search_honda.py`, and `discord_bot.py` are application-level scripts built on top of the library, not the library itself.
   - `.github/workflows/monitor.yml` suggests at least one scheduled/automated monitoring use case.
   - These utilities likely consume the core client, then transform search results into alerts, analytics, or bot messages.

11. **Examples and tests**
   - `examples/` demonstrates the supported use cases and acts as documentation for the architecture of the public API.
   - `test_full_features.py` and `test_moto_1500cc.py` indicate integration-style validation against real or representative Leboncoin flows, especially search scenarios.
   - The `data/` JSON files likely double as fixtures or recorded state for these tests and tools.

12. **Documentation and auxiliary assets**
   - `README.md`, `CHANGELOG.md`, `RESOURCES.md`, and `claude.md` describe usage and project context.
   - The `.claude/skills/*` directories are auxiliary documentation/scripting assets for document processing and PDF handling; they are not part of the Leboncoin client architecture and appear unrelated to the main package.

Main entry points: [`lbc/client.py`](https://github.com/kuaterpillar/lbc/blob/master/lbc/client.py) (Client), [`lbc/mixin/search.py`](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/search.py) (Search), [`lbc/mixin/session.py`](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/session.py) (Session), [`lbc/model/ad.py`](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/ad.py) (Ads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_pkg["lbc<br/>[__init__.py]"]
  node_client["Client<br/>facade<br/>[client.py]"]
  node_session["Session<br/>transport<br/>[session.py]"]
  node_search["Search<br/>query builder<br/>[search.py]"]
  node_ad["Ad lookup<br/>resource api<br/>[ad.py]"]
  node_user["User lookup<br/>resource api<br/>[user.py]"]
  node_ad_model["Ads<br/>domain models<br/>[ad.py]"]
  node_search_model["Searches<br/>domain models<br/>[search.py]"]
  node_user_model["Users<br/>domain models<br/>[user.py]"]
  node_city_model["Geo model<br/>[city.py]"]
  node_proxy_model["Proxy<br/>network model<br/>[proxy.py]"]
  node_enums["Enums<br/>[enums.py]"]
  node_utils["Helpers<br/>utilities<br/>[utils.py]"]
  node_dotenv["Dotenv<br/>config loader<br/>[dotenv.py]"]
end

subgraph group_apps["Apps and tools"]
  node_monitor["Monitor<br/>automation<br/>[monitor.py]"]
  node_analyzer["Analyzer<br/>automation<br/>[market_analyzer.py]"]
  node_bot["Discord bot<br/>automation<br/>[discord_bot.py]"]
  node_search_tool["Search tools<br/>utility scripts<br/>[search_honda.py]"]
end

subgraph group_data["Data and generation"]
  node_fixtures["Data files<br/>json artifacts<br/>[searches.json]"]
  node_generators["Enum generators<br/>codegen"]
end

subgraph group_docs["Docs and examples"]
  node_examples["Examples<br/>usage docs"]
  node_readme["README<br/>documentation<br/>[README.md]"]
end

node_pkg -->|"exports"| node_client
node_client -->|"uses"| node_session
node_client -->|"searches"| node_search
node_client -->|"gets ad"| node_ad
node_client -->|"gets user"| node_user
node_session -->|"accepts"| node_proxy_model
node_session -->|"shares helpers"| node_utils
node_search -->|"returns"| node_search_model
node_search -->|"yields ads"| node_ad_model
node_search -->|"filters by"| node_enums
node_search -->|"uses geo"| node_city_model
node_ad -->|"returns"| node_ad_model
node_user -->|"returns"| node_user_model
node_ad_model -->|"typed by"| node_enums
node_search_model -->|"contains"| node_city_model
node_proxy_model -->|"configures"| node_session
node_dotenv -->|"configures"| node_session
node_generators -->|"generates"| node_enums
node_fixtures -->|"inputs"| node_monitor
node_fixtures -->|"inputs"| node_analyzer
node_examples -->|"demonstrates"| node_client
node_readme -->|"documents"| node_examples
node_monitor -->|"uses"| node_client
node_analyzer -->|"uses"| node_client
node_bot -->|"uses"| node_client
node_search_tool -->|"uses"| node_client

click node_pkg "https://github.com/kuaterpillar/lbc/blob/master/lbc/__init__.py"
click node_client "https://github.com/kuaterpillar/lbc/blob/master/lbc/client.py"
click node_session "https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/session.py"
click node_search "https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/search.py"
click node_ad "https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/ad.py"
click node_user "https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/user.py"
click node_ad_model "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/ad.py"
click node_search_model "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/search.py"
click node_user_model "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/user.py"
click node_city_model "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/city.py"
click node_proxy_model "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/proxy.py"
click node_enums "https://github.com/kuaterpillar/lbc/blob/master/lbc/model/enums.py"
click node_utils "https://github.com/kuaterpillar/lbc/blob/master/lbc/utils.py"
click node_dotenv "https://github.com/kuaterpillar/lbc/blob/master/lbc/dotenv.py"
click node_monitor "https://github.com/kuaterpillar/lbc/blob/master/monitor.py"
click node_analyzer "https://github.com/kuaterpillar/lbc/blob/master/market_analyzer.py"
click node_bot "https://github.com/kuaterpillar/lbc/blob/master/discord_bot.py"
click node_search_tool "https://github.com/kuaterpillar/lbc/blob/master/search_honda.py"
click node_fixtures "https://github.com/kuaterpillar/lbc/blob/master/data/searches.json"
click node_generators "https://github.com/kuaterpillar/lbc/blob/master/utils/generate_enum_categories.py"
click node_examples "https://github.com/kuaterpillar/lbc/blob/master/examples/search_with_args.py"
click node_readme "https://github.com/kuaterpillar/lbc/blob/master/README.md"

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_pkg,node_client,node_session,node_search,node_ad,node_user,node_ad_model,node_search_model,node_user_model,node_city_model,node_proxy_model,node_enums,node_utils,node_dotenv toneBlue
class node_monitor,node_analyzer,node_bot,node_search_tool toneAmber
class node_fixtures,node_generators toneMint
class node_examples,node_readme toneRose
```

## Components

### Core library

Public client, transport, and domain models for the Leboncoin API.

- [lbc](https://github.com/kuaterpillar/lbc/blob/master/lbc/__init__.py): package · Top-level package exports the public client and domain types. · `lbc/__init__.py`
- [Client](https://github.com/kuaterpillar/lbc/blob/master/lbc/client.py): facade · Primary entry point composing the library mixins into one API. · `lbc/client.py`
- [Session](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/session.py): transport · HTTP session, headers, proxy wiring, and request execution. · `lbc/mixin/session.py`
- [Search](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/search.py): query builder · Builds search requests from arguments or full Leboncoin URLs. · `lbc/mixin/search.py`
- [Ad lookup](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/ad.py): resource api · Fetches a single advertisement and related metadata. · `lbc/mixin/ad.py`
- [User lookup](https://github.com/kuaterpillar/lbc/blob/master/lbc/mixin/user.py): resource api · Fetches user profiles and user-related metadata. · `lbc/mixin/user.py`
- [Ads](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/ad.py): domain models · Typed advertisement structures returned by search and lookup flows. · `lbc/model/ad.py`
- [Searches](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/search.py): domain models · Search request and result models used by the query subsystem. · `lbc/model/search.py`
- [Users](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/user.py): domain models · Typed user structures for profile and metadata responses. · `lbc/model/user.py`
- [Geo model](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/city.py): geo models · City, region, and department structures for location-based search. · `lbc/model/city.py`
- [Proxy](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/proxy.py): network model · Proxy configuration object used by the session layer. · `lbc/model/proxy.py`
- [Enums](https://github.com/kuaterpillar/lbc/blob/master/lbc/model/enums.py): value enums · Stable categorical values such as sort order, categories, and owner type. · `lbc/model/enums.py`
- [Helpers](https://github.com/kuaterpillar/lbc/blob/master/lbc/utils.py): utilities · Shared utility helpers and configuration support. · `lbc/utils.py`
- [Dotenv](https://github.com/kuaterpillar/lbc/blob/master/lbc/dotenv.py): config loader · Environment loading helpers for local and operational setup. · `lbc/dotenv.py`

### Apps and tools

Scripts and automations built on top of the library.

- [Monitor](https://github.com/kuaterpillar/lbc/blob/master/monitor.py): automation · Scheduled or long-running monitoring script built on the client. · `monitor.py`
- [Analyzer](https://github.com/kuaterpillar/lbc/blob/master/market_analyzer.py): automation · Market analysis workflow that consumes search and model data. · `market_analyzer.py`
- [Discord bot](https://github.com/kuaterpillar/lbc/blob/master/discord_bot.py): automation · Chatbot integration layered on top of the core client. · `discord_bot.py`
- [Search tools](https://github.com/kuaterpillar/lbc/blob/master/search_honda.py): utility scripts · Ad-hoc scripts for running searches with specific inputs or proxies. · `search_honda.py`

### Data and generation

Persisted artifacts and enum-generation helpers.

- [Data files](https://github.com/kuaterpillar/lbc/blob/master/data/searches.json): json artifacts · Persisted searches, seen ads, prices, and bot configuration. · `data/searches.json`
- [Enum generators](https://github.com/kuaterpillar/lbc/blob/master/utils/generate_enum_categories.py): codegen · Scripts that derive enum and lookup data from source material. · `utils/generate_enum_categories.py`

### Docs and examples

Usage examples and repository documentation.

- [Examples](https://github.com/kuaterpillar/lbc/blob/master/examples/search_with_args.py): usage docs · Executable examples showing the supported public API patterns. · `examples/search_with_args.py`
- [README](https://github.com/kuaterpillar/lbc/blob/master/README.md): documentation · Primary usage and architecture documentation for the package. · `README.md`

## Connections

- lbc → Client: exports · The package exposes the main client entry point.
- Client → Session: uses · Client methods rely on the shared HTTP/session boundary.
- Client → Search: searches · Search is the primary high-volume API path.
- Client → Ad lookup: gets ad · Client exposes single-ad retrieval.
- Client → User lookup: gets user · Client exposes user lookup operations.
- Session → Proxy: accepts · Session configuration can include proxies.
- Session → Helpers: shares helpers · Transport and request logic use common helpers.
- Search → Searches: returns · Search responses are converted into search domain models.
- Search → Ads: yields ads · Search results are normalized into ad objects.
- Search → Enums: filters by · Search parameters use stable categorical enums.
- Search → Geo model: uses geo · Location filters depend on geography models.
- Ad lookup → Ads: returns · Single-ad fetches produce ad models.
- User lookup → Users: returns · User lookup produces user models.
- Ads → Enums: typed by · Ad fields use library enums for categories and metadata.
- Searches → Geo model: contains · Search structures include location-aware data.
- Proxy → Session: configures · Proxy objects feed into session setup.
- Dotenv → Session: configures · Environment loading supports transport configuration.
- Enum generators → Enums: generates · Code generation scripts maintain enum and lookup data.
- Data files → Monitor: inputs · Persisted JSON state supports monitoring and analytics workflows.
- Data files → Analyzer: inputs · Analytics scripts consume stored searches and price data.
- Examples → Client: demonstrates · Examples show the public client usage patterns.
- README → Examples: documents · The README points to example workflows.
- Monitor → Client: uses · Monitoring automation is built on the core client.
- Analyzer → Client: uses · Analysis tooling uses the same library API.
- Discord bot → Client: uses · Bot integration consumes library search and lookup APIs.
- Search tools → Client: uses · Ad-hoc scripts call into the client for searches.
