# vexedwilosn/aetherswap architecture

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

- Interactive diagram: https://gitdiagram.com/vexedwilosn/aetherswap
- Repository: https://github.com/vexedwilosn/aetherswap

## Overview

1. **Project shape and runtime**
   - AetherSwap is a Python 3.10+ FastAPI application with a local web console. The main entry points are `run.py` and `app/main.py`, and the server is designed to run either as a desktop-style local service or as a Linux-hosted API/UI backend.
   - The architecture is centered around a single backend process that exposes HTTP routes, serves static frontend assets, and runs background automation workers.

2. **Presentation layer**
   - The `web/` directory contains a plain HTML/CSS/JavaScript dashboard, not a frontend framework app.
   - Frontend modules such as `accounts.js`, `gift.js`, `proxy.js`, `settings.js`, `steamDeals.js`, and `transactions.js` talk to backend endpoints and render operational state, configuration, market data, and transaction history.

3. **API boundary**
   - `app/routes/` is the main HTTP boundary, split by domain: accounts, auth, config, gift, inventory, pipeline, proxy, status, steam deals, transactions, and static assets.
   - This layer is the contract between the UI and the backend core; it handles requests, returns current state, and triggers automation workflows without embedding the business logic itself.

4. **Core orchestration layer**
   - The business workflow lives in `app/pipeline.py`, `app/pipeline_steps.py`, `app/receive_flow.py`, and `app/sell_pipeline.py`.
   - These modules coordinate the two major domain pipelines described in the README: a buy/acquisition pipeline and a sell/listing pipeline. `app/pipeline_context.py` and `app/state.py` carry shared execution state and control flags across steps.

5. **Acquisition flow**
   - The buy path starts from market discovery and filtering, then applies stability checks and purchase guards before placing orders on Buff.
   - Relevant subsystems include `app/analysis/stability.py`, `app/purchase_limit.py`, `app/shared_market.py`, `app/inventory_cs2.py`, and the Buff client/service modules. This path is where CV/R²-based screening and daily limit checks are enforced before a purchase can proceed.

6. **Sell / inventory flow**
   - The sell path is driven by inventory observation and listing automation: new items are detected, priced, listed, confirmed, and finally persisted as transaction records.
   - Modules such as `app/steam_listings.py`, `app/steam_delist.py`, `app/steam_confirm.py`, `app/sync_sold.py`, and `app/repair_error_records.py` support listing lifecycle management and recovery of inconsistent records.

7. **External service integrations**
   - Steam integration is spread across `steam/` and `app/services/steam_*`: client/session/inventory/market/orders plus Steam login and confirmation helpers.
   - Buff integration is encapsulated in `buff/` and `app/services/buff_*`, which handle authentication and purchase execution.
   - SteamDT market data ingestion lives in `steamdt/` and `app/services/analysis_client.py` / `steam_deals.py`, which provide historical and live market inputs for analysis and deal discovery.

8. **Automation, queues, and workers**
   - Background execution is handled by `app/services/task_queue.py` and `app/services/workers.py`, with retry behavior in `app/services/retry.py`.
   - This layer decouples long-running or polling tasks from request/response handling, which is important for login refreshes, market polling, inventory watching, notifications, and confirmation loops.

9. **Persistence and configuration**
   - Data persistence is implemented in `app/database.py` using SQLModel/SQLite, with domain records for accounts, transactions, and operational history.
   - Configuration is loaded and validated through `app/config_loader.py` and `app/config_schema.py`, with `config/config.json` as the default config source. `app/state.py` appears to hold runtime flags separate from persisted settings.

10. **Security, identity, and network control**
   - Authentication and identity handling are split across `app/services/steam_auth.py`, `app/services/buff_auth.py`, `app/steam_confirm.py`, and related account routes.
   - Proxy and throttling concerns are first-class: `utils/proxy_manager.py`, `utils/throttle.py`, `utils/delay.py`, and `utils/network_check.py` support rate limiting, request spacing, and network adaptation for Steam/Buff access.
   - Sensitive inputs like cookies, `shared_secret`, and `identity_secret` are treated as local runtime secrets rather than externalized credentials.

11. **Analytics and decision support**
   - The `analysis/` package, especially `analysis/stability.py`, provides the statistical filtering used for item selection and risk control.
   - Utility modules such as `utils/trend.py`, `utils/money.py`, and `app/services/deal_cards.py` support pricing, trend evaluation, formatting, and presentation of market opportunities.

12. **Operational data flow**
   - The end-to-end flow is: user configures the system in the web UI → routes update persisted config/state → worker tasks call Steam/Buff/SteamDT services → pipeline steps make purchase/listing decisions → transactions are saved to SQLite → UI reads back status and analytics.
   - Notifications and alerts are sent through `app/notify.py`, making the system observable even when the user is not watching the console.

13. **Testing boundary**
   - `tests/` covers key architectural boundaries: config validation, database behavior, proxy management, pipeline locks, pipeline steps, market orders, buff verification, and sell-pipeline currency guards.
   - These tests indicate the repo’s critical seams: configuration correctness, concurrency control, external-service wrappers, and business-rule enforcement.

Main entry points: [`app/routes`](https://github.com/vexedwilosn/aetherswap/tree/main/app/routes) (API routes), [`app/pipeline_steps.py`](https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline_steps.py) (Pipeline steps), [`app/services/workers.py`](https://github.com/vexedwilosn/aetherswap/blob/main/app/services/workers.py) (Workers), [`steam/client.py`](https://github.com/vexedwilosn/aetherswap/blob/main/steam/client.py) (Steam services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_web_ui["Web UI<br/>static console<br/>[index.html]"]
  node_web_js["UI modules<br/>browser scripts<br/>[main.js]"]
end

subgraph group_api["HTTP API"]
  node_run_py["run.py<br/>entrypoint<br/>[run.py]"]
  node_app_main["App main<br/>app startup<br/>[main.py]"]
  node_routes["API routes<br/>http routes"]
  node_api_core["API glue<br/>app facade<br/>[api.py]"]
end

subgraph group_core["Core Orchestration"]
  node_pipeline["Pipeline core<br/>workflow orchestration<br/>[pipeline.py]"]
  node_pipeline_steps["Pipeline steps<br/>workflow steps<br/>[pipeline_steps.py]"]
  node_buy_flow["Buy flow<br/>acquisition flow<br/>[receive_flow.py]"]
  node_sell_pipeline["Sell flow<br/>listing flow<br/>[sell_pipeline.py]"]
  node_pipeline_ctx["Pipeline state<br/>runtime context"]
  node_analysis["Analysis<br/>risk scoring<br/>[stability.py]"]
end

subgraph group_integrations["External Integrations"]
  node_steam["Steam services<br/>integration<br/>[client.py]"]
  node_buff["Buff services<br/>integration<br/>[buyer.py]"]
  node_steamdt["SteamDT data<br/>market data<br/>[fetcher.py]"]
end

subgraph group_data["Data & Config"]
  node_state["Runtime state<br/>flags<br/>[state.py]"]
  node_database[("SQLite DB<br/>persistence<br/>[database.py]")]
  node_config["Config loader<br/>configuration<br/>[config_loader.py]"]
end

subgraph group_ops["Operations"]
  node_workers["Workers<br/>background jobs<br/>[workers.py]"]
  node_task_queue["Task queue<br/>job queue<br/>[task_queue.py]"]
  node_retry["Retry policy<br/>resilience<br/>[retry.py]"]
  node_utils["Network utils<br/>control helpers<br/>[proxy_manager.py]"]
  node_notify["Notifications<br/>alerts<br/>[notify.py]"]
end

node_run_py -->|"starts"| node_app_main
node_app_main -->|"mounts"| node_routes
node_app_main -->|"starts"| node_workers
node_web_ui -->|"calls"| node_routes
node_web_js -->|"fetches"| node_routes
node_routes -->|"delegates"| node_api_core
node_routes -->|"triggers"| node_pipeline
node_routes -->|"reads/writes"| node_state
node_routes -->|"persists"| node_database
node_routes -->|"loads"| node_config
node_routes -->|"uses"| node_steam
node_routes -->|"uses"| node_buff
node_pipeline -->|"orchestrates"| node_pipeline_steps
node_pipeline -->|"shares state"| node_pipeline_ctx
node_pipeline_steps -->|"filters"| node_analysis
node_pipeline_steps -->|"scores markets"| node_steamdt
node_pipeline_steps -->|"executes"| node_steam
node_pipeline_steps -->|"executes"| node_buff
node_pipeline_steps -->|"guards"| node_utils
node_pipeline_steps -->|"alerts"| node_notify
node_buy_flow -->|"checks"| node_analysis
node_buy_flow -->|"buys"| node_buff
node_sell_pipeline -->|"lists"| node_steam
node_sell_pipeline -->|"records"| node_database
node_workers -->|"consumes"| node_task_queue
node_workers -->|"retries"| node_retry
node_workers -->|"polls"| node_steam
node_workers -->|"polls"| node_buff
node_workers -->|"ingests"| node_steamdt
node_workers -->|"emits"| node_notify
node_config -->|"initializes"| node_state
node_steam -->|"depends on"| node_utils
node_buff -->|"depends on"| node_utils

click node_run_py "https://github.com/vexedwilosn/aetherswap/blob/main/run.py"
click node_app_main "https://github.com/vexedwilosn/aetherswap/blob/main/app/main.py"
click node_web_ui "https://github.com/vexedwilosn/aetherswap/blob/main/web/index.html"
click node_web_js "https://github.com/vexedwilosn/aetherswap/blob/main/web/js/main.js"
click node_routes "https://github.com/vexedwilosn/aetherswap/tree/main/app/routes"
click node_api_core "https://github.com/vexedwilosn/aetherswap/blob/main/app/api.py"
click node_pipeline "https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline.py"
click node_pipeline_steps "https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline_steps.py"
click node_buy_flow "https://github.com/vexedwilosn/aetherswap/blob/main/app/receive_flow.py"
click node_sell_pipeline "https://github.com/vexedwilosn/aetherswap/blob/main/app/sell_pipeline.py"
click node_pipeline_ctx "https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline_context.py"
click node_state "https://github.com/vexedwilosn/aetherswap/blob/main/app/state.py"
click node_database "https://github.com/vexedwilosn/aetherswap/blob/main/app/database.py"
click node_config "https://github.com/vexedwilosn/aetherswap/blob/main/app/config_loader.py"
click node_workers "https://github.com/vexedwilosn/aetherswap/blob/main/app/services/workers.py"
click node_task_queue "https://github.com/vexedwilosn/aetherswap/blob/main/app/services/task_queue.py"
click node_retry "https://github.com/vexedwilosn/aetherswap/blob/main/app/services/retry.py"
click node_steam "https://github.com/vexedwilosn/aetherswap/blob/main/steam/client.py"
click node_buff "https://github.com/vexedwilosn/aetherswap/blob/main/buff/buyer.py"
click node_steamdt "https://github.com/vexedwilosn/aetherswap/blob/main/steamdt/fetcher.py"
click node_analysis "https://github.com/vexedwilosn/aetherswap/blob/main/analysis/stability.py"
click node_utils "https://github.com/vexedwilosn/aetherswap/blob/main/utils/proxy_manager.py"
click node_notify "https://github.com/vexedwilosn/aetherswap/blob/main/app/notify.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_web_ui,node_web_js toneBlue
class node_run_py,node_app_main,node_routes,node_api_core toneAmber
class node_pipeline,node_pipeline_steps,node_buy_flow,node_sell_pipeline,node_pipeline_ctx,node_analysis toneMint
class node_steam,node_buff,node_steamdt toneRose
class node_state,node_database,node_config toneIndigo
class node_workers,node_task_queue,node_retry,node_utils,node_notify toneTeal
```

## Components

### Presentation

Local web console and browser-side modules

- [Web UI](https://github.com/vexedwilosn/aetherswap/blob/main/web/index.html): static console · Plain HTML/CSS/JS dashboard · `web/index.html`
- [UI modules](https://github.com/vexedwilosn/aetherswap/blob/main/web/js/main.js): browser scripts · Client-side modules for accounts, settings, proxies, deals, and transactions · `web/js/main.js`

### HTTP API

FastAPI route boundary and app entrypoints

- [run.py](https://github.com/vexedwilosn/aetherswap/blob/main/run.py): entrypoint · Top-level launcher for the local service · `run.py`
- [App main](https://github.com/vexedwilosn/aetherswap/blob/main/app/main.py): app startup · FastAPI application bootstrap and server setup · `app/main.py`
- [API routes](https://github.com/vexedwilosn/aetherswap/tree/main/app/routes): http routes · Domain HTTP endpoints for UI and automation control · `app/routes`
- [API glue](https://github.com/vexedwilosn/aetherswap/blob/main/app/api.py): app facade · Application-level API wiring and shared request handling · `app/api.py`

### Core Orchestration

Pipelines, shared state, and workflow control

- [Pipeline core](https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline.py): workflow orchestration · Main buy/sell workflow coordination · `app/pipeline.py`
- [Pipeline steps](https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline_steps.py): workflow steps · Step-level execution and branching logic · `app/pipeline_steps.py`
- [Buy flow](https://github.com/vexedwilosn/aetherswap/blob/main/app/receive_flow.py): acquisition flow · Receive and purchase path for market acquisition · `app/receive_flow.py`
- [Sell flow](https://github.com/vexedwilosn/aetherswap/blob/main/app/sell_pipeline.py): listing flow · Inventory listing and sell-side automation · `app/sell_pipeline.py`
- [Pipeline state](https://github.com/vexedwilosn/aetherswap/blob/main/app/pipeline_context.py): runtime context · Shared execution context and control flags · `app/pipeline_context.py`
- [Analysis](https://github.com/vexedwilosn/aetherswap/blob/main/analysis/stability.py): risk scoring · Stability and statistical filtering for item selection · `analysis/stability.py`

### External Integrations

Steam, Buff, and market-data adapters

- [Steam services](https://github.com/vexedwilosn/aetherswap/blob/main/steam/client.py): integration · Steam client, session, inventory, market, and confirmations · `steam/client.py`
- [Buff services](https://github.com/vexedwilosn/aetherswap/blob/main/buff/buyer.py): integration · Buff authentication and purchase execution · `buff/buyer.py`
- [SteamDT data](https://github.com/vexedwilosn/aetherswap/blob/main/steamdt/fetcher.py): market data · Historical and live market data ingestion · `steamdt/fetcher.py`

### Data & Config

Persistence, config, and runtime state

- [Runtime state](https://github.com/vexedwilosn/aetherswap/blob/main/app/state.py): flags · In-memory operational flags separate from persisted settings · `app/state.py`
- [SQLite DB](https://github.com/vexedwilosn/aetherswap/blob/main/app/database.py): persistence · SQLModel-backed storage for accounts, transactions, and history · `app/database.py`
- [Config loader](https://github.com/vexedwilosn/aetherswap/blob/main/app/config_loader.py): configuration · Schema validation and config file loading · `app/config_loader.py`

### Operations

Background execution, retries, notifications, and safety controls

- [Workers](https://github.com/vexedwilosn/aetherswap/blob/main/app/services/workers.py): background jobs · Long-running polling and automation workers · `app/services/workers.py`
- [Task queue](https://github.com/vexedwilosn/aetherswap/blob/main/app/services/task_queue.py): job queue · Queued execution for long-running tasks · `app/services/task_queue.py`
- [Retry policy](https://github.com/vexedwilosn/aetherswap/blob/main/app/services/retry.py): resilience · Retry and backoff behavior for unreliable operations · `app/services/retry.py`
- [Network utils](https://github.com/vexedwilosn/aetherswap/blob/main/utils/proxy_manager.py): control helpers · Proxy, throttle, delay, time, and trend helpers · `utils/proxy_manager.py`
- [Notifications](https://github.com/vexedwilosn/aetherswap/blob/main/app/notify.py): alerts · User-facing status and alert delivery · `app/notify.py`

## Connections

- run.py → App main: starts · Launcher boots the FastAPI app
- App main → API routes: mounts · Registers HTTP routes and static handling
- App main → Workers: starts · Initializes background automation
- Web UI → API routes: calls · Dashboard reads and mutates backend state through the API
- UI modules → API routes: fetches · Browser modules drive endpoint interactions
- API routes → API glue: delegates · Route layer forwards to shared app logic
- API routes → Pipeline core: triggers · Endpoints start or control workflows
- API routes → Runtime state: reads/writes · Status and control endpoints expose runtime flags
- API routes → SQLite DB: persists · Account, config, and transaction state is stored
- API routes → Config loader: loads · Config endpoints validate and update settings
- API routes → Steam services: uses · Auth, inventory, and confirmation routes call Steam adapters
- API routes → Buff services: uses · Auth and purchase routes call Buff adapters
- Pipeline core → Pipeline steps: orchestrates · Main workflow executes step sequence
- Pipeline core → Pipeline state: shares state · Execution context passes across steps
- Pipeline steps → Analysis: filters · Stability checks guide acquisition decisions
- Pipeline steps → SteamDT data: scores markets · Market data feeds analysis and deal discovery
- Pipeline steps → Steam services: executes · Steps interact with Steam inventory and orders
- Pipeline steps → Buff services: executes · Steps place purchases through Buff
- Pipeline steps → Network utils: guards · Throttle, proxy, and network helpers protect external calls
- Pipeline steps → Notifications: alerts · Workflow progress and failures are reported
- Buy flow → Analysis: checks · Buy path applies stability and purchase guards
- Buy flow → Buff services: buys · Acquisition culminates in Buff purchase execution
- Sell flow → Steam services: lists · Sell path manages Steam listings and confirmations
- Sell flow → SQLite DB: records · Completed sales and recoveries persist to SQLite
- Workers → Task queue: consumes · Workers run queued background jobs
- Workers → Retry policy: retries · Unstable tasks use retry policy
- Workers → Steam services: polls · Background jobs refresh Steam state and confirmations
- Workers → Buff services: polls · Background jobs refresh Buff-related state
- Workers → SteamDT data: ingests · Market polling and deal discovery use SteamDT feeds
- Workers → Notifications: emits · Workers generate operational notifications
- Config loader → Runtime state: initializes · Loaded config seeds runtime flags and behavior
- Steam services → Network utils: depends on · Steam access is shaped by proxy and throttle controls
- Buff services → Network utils: depends on · Buff access is shaped by proxy and throttle controls
