How vexedwilosn/aetherswap works
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: routes API routes · pipeline_steps.py Pipeline steps · workers.py Workers · client.py Steam services
Components 23
Presentation
Local web console and browser-side modules
- Web UI · Plain HTML/CSS/JS dashboard
web/index.html - UI modules · Client-side modules for accounts, settings, proxies, deals, and transactions
web/js/main.js
HTTP API
FastAPI route boundary and app entrypoints
- run.py · Top-level launcher for the local service
run.py - App main · FastAPI application bootstrap and server setup
app/main.py - API routes · Domain HTTP endpoints for UI and automation control
app/routes - API glue · Application-level API wiring and shared request handling
app/api.py
Core Orchestration
Pipelines, shared state, and workflow control
- Pipeline core · Main buy/sell workflow coordination
app/pipeline.py - Pipeline steps · Step-level execution and branching logic
app/pipeline_steps.py - Buy flow · Receive and purchase path for market acquisition
app/receive_flow.py - Sell flow · Inventory listing and sell-side automation
app/sell_pipeline.py - Pipeline state · Shared execution context and control flags
app/pipeline_context.py - Analysis · Stability and statistical filtering for item selection
analysis/stability.py
External Integrations
Steam, Buff, and market-data adapters
- Steam services · Steam client, session, inventory, market, and confirmations
steam/client.py - Buff services · Buff authentication and purchase execution
buff/buyer.py - SteamDT data · Historical and live market data ingestion
steamdt/fetcher.py
Data & Config
Persistence, config, and runtime state
- Runtime state · In-memory operational flags separate from persisted settings
app/state.py - SQLite DB · SQLModel-backed storage for accounts, transactions, and history
app/database.py - Config loader · Schema validation and config file loading
app/config_loader.py
Operations
Background execution, retries, notifications, and safety controls
- Workers · Long-running polling and automation workers
app/services/workers.py - Task queue · Queued execution for long-running tasks
app/services/task_queue.py - Retry policy · Retry and backoff behavior for unreliable operations
app/services/retry.py - Network utils · Proxy, throttle, delay, time, and trend helpers
utils/proxy_manager.py - Notifications · User-facing status and alert delivery
app/notify.py
Connections 33
- 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