Architecture¶
The bot is moving from a single script to a layered design
(ADR 0001). The
migration roadmap tracks where it stands. This page
describes the code as it is on master.
Contents¶
- Layers
- Startup
- Data flow
- Handling one signal
- How a signal can end
- Domain model
- Application
- Adapters
- Composition root
- Decisions
Layers¶
| Layer | Package | May depend on | Holds |
|---|---|---|---|
| Domain | tradelocker_bot.domain |
standard library | Trading rules as plain values and functions, with no I/O |
| Application | tradelocker_bot.application |
domain | Use cases and the ports they need |
| Adapters | tradelocker_bot.adapters |
application, domain, third-party clients | TradeLocker client and login, operator console, system clock, HTTP webhook, signal handler, secret files, Telegram chat and notifier |
| Composition root | tradelocker_bot.composition_root |
everything above | Start settings, banners, wiring, the lock, the server start |
| Entrypoint | main_without_ssl.py |
the composition root | The container's command; calls main() and nothing else |
Every arrow below is an import in the code. The entrypoint keeps its name because the container command is part of the frozen contract (roadmap).
flowchart TB
EP[main_without_ssl.py<br/>container command]
CR[composition_root<br/>parse_args, main, build_signal_handler]
subgraph adapters [tradelocker_bot.adapters]
WH[webhook<br/>create_app]
SL[server_log<br/>server_log_config]
SH[signal_handler<br/>SignalHandler]
TLB[tradelocker_broker<br/>TradeLockerBroker, log_in]
PC[console<br/>PrintingConsole]
SC[system_clock<br/>SystemClock]
AA[ascii_alerts<br/>colours, banners]
WP[webhook_path<br/>random_webhook_path]
PF[secret_file<br/>read_secret_file]
TG[telegram<br/>telegram_from, TelegramChat]
NT[notifier<br/>BackgroundNotifier,<br/>Chat port, SendFailure]
DLV[delivery<br/>Delivery]
SHW[shown<br/>shown]
end
subgraph application [tradelocker_bot.application]
ES[ExecuteSignal]
PORTS[ports: Broker, OperatorConsole, Clock,<br/>BrokerFailure, OrderRejected]
REF[refusal: NoBalance, UnknownSymbol]
end
subgraph domain [tradelocker_bot.domain]
SIG[signal: parse_signal, OpenSignal, CloseSignal, Side]
LS[lot_sizing: LotSizing, UnusableQuantity]
RES[result: Ok, Err]
end
EP --> CR
CR --> WH & SL & SH & TLB & PC & SC & AA & WP & PF & TG & NT & DLV & ES
PF --> RES
TG --> PF & SHW & NT & RES
NT --> AA & PORTS & RES
DLV --> NT & PORTS & RES
SH --> PC & ES & PORTS & RES & SIG
TLB --> PORTS & RES & SIG
PC --> AA & SHW & REF & LS & SIG
ES --> PORTS & REF & LS & RES & SIG
PORTS --> RES & SIG
REF --> LS
SIG --> LS & RES
LS --> RES
WH --> FASTAPI[(FastAPI)]
CR --> UVICORN[(uvicorn)]
SL --> UVICORN
TLB --> CLIENT[(tradelocker client)]
SC --> TIME[(time: monotonic, sleep)]
PF --> FILE[(the password and token files)]
TG --> TGAPI[(api.telegram.org, through urllib)]
Dependencies point inwards only. tests/test_layer_dependencies.py enforces
this for the inner layers with an explicit allow-list:
- The domain may import its own package and a named set of pure
standard-library modules (
dataclasses,enum,math,typingand similar). - The application may import the same, plus the domain.
- Anything else fails, including
datetime(the clock),random,os, the adapters and every third-party package. - The same test forbids builtins that do I/O or load code, such as
open,printandeval, in both layers.
Adapters exist to depend on third-party clients, so the allow-list does not
cover them. The same test keeps them inward of the composition root: an
adapter may import neither composition_root nor main_without_ssl, so no
adapter can reach another's wiring, such as the shared lock or the
logged-in client, behind the root's back
(ADR 0010).
Startup¶
sequenceDiagram
autonumber
participant EP as main_without_ssl.py
participant CR as composition_root.main
participant TB as tradelocker_broker.log_in
participant WH as webhook.create_app
participant SL as server_log
participant U as uvicorn
EP->>CR: main()
CR->>CR: stdout to line buffering (ADR 0026)
CR->>CR: parse_args: the environment, then the options,<br/>then the password from password_file or password,<br/>then telegram_token_file and telegram_chat_id<br/>(exit 2 on a bad, missing or empty setting, --password,<br/>both password sources, a password file that is not one line,<br/>a url without a leading / or with a brace, ?, # or %,<br/>one Telegram setting alone, a file with no bot token, a bad chat id)
opt the Telegram settings are set
CR->>CR: start_notifier: the notifier's thread (ADR 0027)
end
opt --url generate
CR->>CR: print the URL banner and random_webhook_path()
end
CR->>CR: print the greeting, and Telegram: on when it is
CR->>CR: int(acc_num), int(acc_id)
CR->>TB: log_in(env, credentials, selectors)
TB-->>CR: TLAPI client at log level info<br/>(or the client's exception:<br/>Login failed: queued, then raised)
CR->>CR: print Logged in: acc_id, acc_num, and notify it
CR->>CR: build_signal_handler(client, one Lock, SystemClock, notify)
CR->>WH: create_app(url, handler.handle)
WH-->>CR: FastAPI app
CR->>SL: server_log_config()
SL-->>CR: uvicorn's log settings,<br/>access line without the request line
CR->>U: run(app, host="0.0.0.0", port, log_config)
U-->>CR: returns once the server stops
Note over EP,U: main's finally: end(5 s). Python waits for the webhook's threads,<br/>then runs the notifier's exit function, until those 5 s run out,<br/>at least 2 s (ADR 0029), and nothing is sent after its report
A bad setting stops at step 3, a bad account selector at step 7, and a failed login at step 8. Each leaves every later step undone, so the server never starts on a half-built bot.
Data flow¶
What happens to one alert, from TradingView to the broker. Text from the webhook becomes a typed signal at the first step and stays typed from then on.
flowchart LR
TV[TradingView alert] -- "POST, 7 lines of text" --> WH[webhook route<br/>adapters.webhook]
WH -- "200 OK at once: received,<br/>not the outcome" --> TV
WH -- "lines, in a background thread" --> SH[SignalHandler<br/>adapters.signal_handler]
SH --> P[parse_signal<br/>domain]
P -- "Err(InvalidSignal)" --> CON[PrintingConsole<br/>stdout]
P -- "Ok(OpenSignal or CloseSignal)" --> LOCK{{global lock}}
LOCK --> UC[ExecuteSignal<br/>application]
UC -- "Broker port" --> TLB[TradeLockerBroker<br/>adapter]
TLB -- "HTTPS" --> API[(TradeLocker API)]
UC -- "OperatorConsole port" --> CON
UC -- "Clock port: now, sleep" --> CLK[SystemClock<br/>adapter]
UC -- "Err(Refusal)" --> CON
UC -- "Err(BrokerFailure)" --> SH
SH -- "Broker failed: line,<br/>then re-raised in the thread" --> CON
CON -- "red lines, Closed line:<br/>notify(text)" --> NT[BackgroundNotifier<br/>its own thread]
NT -- "HTTPS, when set" --> TGAPI[(Telegram chat)]
The console's red lines, and the green Closed: line that ends a
Still closing: one
(ADR 0028), reach Telegram only
when its settings are set,
and only through the notifier's queue, so no signal waits on Telegram
(ADR 0027).
| Value | Made by | Read by |
|---|---|---|
webhook lines (list[str]) |
create_app's route |
SignalHandler.handle, then parse_signal |
OpenSignal / CloseSignal |
parse_signal |
ExecuteSignal |
InvalidSignal |
parse_signal |
PrintingConsole.rejected |
balance (float or None) |
TradeLockerBroker |
ExecuteSignal, then LotSizing |
quantity (float) |
LotSizing.quantity_for |
Broker.place_market_order |
instrument id (int or None) |
TradeLockerBroker |
ExecuteSignal |
Refusal |
ExecuteSignal, LotSizing |
PrintingConsole.rejected |
OrderRejected |
TradeLockerBroker |
ExecuteSignal, which reports it through OperatorConsole.order_rejected |
BrokerFailure |
TradeLockerBroker |
SignalHandler, which re-raises its cause |
Handling one signal¶
open¶
sequenceDiagram
autonumber
participant H as SignalHandler
participant UC as ExecuteSignal
participant B as Broker (TradeLockerBroker)
participant C as OperatorConsole
participant K as Clock
H->>H: parse_signal(lines) = OpenSignal
H->>H: acquire lock
H->>UC: execute(signal)
UC->>B: account_balance()
B-->>UC: Ok(1000.0)
UC->>UC: sizing.quantity_for(1000.0) = Ok(0.1)
UC->>B: instrument_id("XAUUSD")
B-->>UC: Ok(101)
UC->>C: locked()
UC->>B: open_position_count(101)
B-->>UC: Ok(n)
opt n > 0
loop n times
UC->>B: request_close(101)
UC->>C: closing("XAUUSD")
end
UC->>K: now()
loop until the broker lists no position on 101
UC->>B: open_position_count(101), at once
B-->>UC: Ok(n)
opt a minute since the first requests, once
UC->>C: still_closing("XAUUSD", n, seconds)
end
alt 10 s on the clock since the last requests went out
UC->>B: request_close(101), n times, with closing("XAUUSD")
UC->>K: now()
else
UC->>K: sleep(1)
end
end
opt still_closing was printed
UC->>K: now()
UC->>C: closed("XAUUSD", seconds since the first requests)
end
end
UC->>B: place_market_order(101, 0.1, side, sl, tp), once
alt the broker created the order
B-->>UC: Ok(order id)
UC->>C: order_placed(id)
UC->>C: unlocked()
UC-->>H: Ok(None)
else the broker answered without one
B-->>UC: Err(OrderRejected(reason))
UC->>B: open_position_count(101), again
B-->>UC: Ok(n)
UC->>C: order_rejected("XAUUSD", side, reason, n)
UC->>C: unlocked()
UC-->>H: Err(OrderRejected(reason))
end
H->>H: release lock
Steps 4 to 8 can end the signal early (ADR 0009). No balance, an unusable
quantity or an unknown symbol is a Refusal. A call that fails is a
BrokerFailure. Either way nothing has been closed yet.
The close has no time limit. After a request the positions are counted
again at once, since a close usually fills by then. While one stays open,
the use case pauses a second between counts, on top of the second the
client waits before every request, and asks again only once 10 seconds
have passed on the Clock. A minute after the first request it prints one
red Still closing: line. A count or request that gets no answer still
ends the loop as a BrokerFailure
(ADR 0022). A close that
printed that line ends with one green Closed: line, at
the count that lists no position; one that failed does not
(ADR 0028).
The order is placed once. If the broker answers without creating it, the
positions are already closed. The use case counts them again, since a
resent order may have filled, and prints one red Order rejected: line
with the broker's reason and what the broker lists now, then
Normal: Unlocked; the thread ends normally. An order request that gets no
answer is a BrokerFailure and still raises, since the order may exist
(ADR 0021).
close¶
sequenceDiagram
autonumber
participant H as SignalHandler
participant UC as ExecuteSignal
participant B as Broker
participant C as OperatorConsole
participant K as Clock
H->>H: parse_signal(lines) = CloseSignal
H->>H: acquire lock
H->>UC: execute(signal)
UC->>B: instrument_id("XAUUSD")
B-->>UC: Ok(101)
UC->>C: locked()
loop until the broker lists no position on 101
UC->>B: open_position_count(101)
UC->>B: request_close(101), once per row, every 10 s
UC->>C: closing("XAUUSD"), once per request
UC->>K: sleep(1) before a count that follows no request
end
UC->>C: unlocked()
UC-->>H: Ok(None)
H->>H: release lock
close sizes nothing, so it reads no balance (ADR 0008).
How a signal can end¶
stateDiagram-v2
[*] --> Received
Received --> Rejected: payload error (InvalidSignal)
Received --> Locked: valid signal
Locked --> Refused: no balance, unusable quantity, unknown symbol
Locked --> Failed: broker call failed before any close
Locked --> Working: checks passed, Normal Locked line
Working --> Working: position still open, Still closing line once after a minute
Working --> Working: closed after that line, Closed line once
Working --> Failed: broker call failed while closing or ordering
Working --> OrderRejected: broker answered the order without creating it
Working --> Handled: Normal Unlocked line
Rejected --> [*]: one red line, no broker call, no lock
Refused --> [*]: one red line, nothing closed
OrderRejected --> [*]: one red line with a fresh count, Normal Unlocked line
Failed --> [*]: Broker failed or Bot failed line, the exception re-raised in the thread
Handled --> [*]
| End | Broker calls | Positions touched | Operator sees | Thread |
|---|---|---|---|---|
| Rejected | none | no | Signal rejected: line N ... |
ends normally |
| Refused | balance and/or lookup | no | Signal rejected: ... |
ends normally |
| Order rejected | all, order once, a recount | closed, none opened | Order rejected: ..., Unlocked |
ends normally |
| Failed | up to the failing one | possibly closed | Broker failed: ..., then the client's traceback |
raises |
| Handled | all | replaced or closed | Normal: Locked ... Unlocked |
ends normally |
The webhook answers 200 OK before any of this, so the caller never learns
the outcome. That is by decision: the answer acknowledges receipt.
TradingView cancels a request not answered within three seconds, which a
signal that trades already takes, and sends an alert again after a 5xx,
so an answer after handling would be cancelled and one by outcome could run
the signal twice. Only a body that is not UTF-8 answers otherwise, 500,
and it starts no thread (ADR 0023).
Domain model¶
parse_signalturns the webhook's lines into anOpenSignalor aCloseSignal, or returns the firstInvalidSignal. It runs before any broker call (ADR 0008). AnOpenSignalalready holds theSideto trade, with the inversion applied.LotSizingis the position size per unit of account balance, parsed from the webhook's<lot>/<balance step>field. Both numbers must be positive and finite, and the constructor refuses anything else.quantity_forreturns the rounded lots for a balance. If that number is not finite or not above zero, it returnsUnusableQuantityinstead (ADR 0009).Sideisbuyorsell, with itsopposite.Ok/Err(Result) is an outcome returned as a value. A result refuses truth testing, so a forgotten unwrap fails loudly (ADR 0006).
Application¶
ADR 0005 describes the design.
ExecuteSignalruns one valid signal.closelooks up the instrument and closes its positions.openreads the balance, sizes the position and looks up the instrument. Only then does it close the instrument's positions and place a market order.- The instrument is looked up once.
- The close waits, with no time limit, until the broker lists no
position. It counts again at once after a request, then a second
apart, asks again every 10 seconds on the
Clock, and reports a close still open a minute after the first request once (ADR 0022). - The order is placed once (ADR 0021).
executereturnsOk(None), aRefusal, anOrderRejectedor the firstBrokerFailure.- A
Refusal(NoBalance,UnknownSymbol,UnusableQuantity) means the broker answered and ruled the signal out. It always comes before any close request (ADR 0009). - An
OrderRejectedmeans the broker answered the order without creating it. It comes after the close, and holds the broker's reason orNone. The use case reports it with a fresh position count before returning it (ADR 0021). - A
BrokerFailuremeans a broker call did not answer. It holds the client's own exception (ADR 0006).
- A
Broker,OperatorConsoleandClockare its ports, one per process boundary.Clockgivesnow(), seconds that never go back, andsleep(seconds).Broker.account_balancereturnsOk(None)when the answer holds no number.Broker.instrument_idreturnsOk(None)for a name the broker does not list. ItsErrmeans only that the broker did not answer.Broker.place_market_orderreturns an id only for an order the broker created; otherwiseOrderRejectedorBrokerFailure.
Adapters¶
TradeLockerBrokerimplementsBrokerover thetradelockerclient.- Each method makes the legacy handler's call with the same arguments.
The exception is the instrument lookup, which reads the instrument list
rather than parsing the client's
ValueError(ADR 0009). - Only the client call runs inside the exception guard. A fault in the adapter's own handling of the answer raises, so it cannot pose as an outage.
- The client's
TLAPIOrderException, andNonefor an order, becomeOrderRejectedwith the broker'serrmsg, else its whole answer; every other client exception stays aBrokerFailure(ADR 0021). log_in, in the same module, logs in to the demo or live server, on the account that--acc_numor--acc_idnames. It refuses both at once before sending any credentials. It runs the client atinfo(CLIENT_LOG_LEVEL): at its default,debug, the client logs each request whole, the password and tokens included (ADR 0025).
- Each method makes the legacy handler's call with the same arguments.
The exception is the instrument lookup, which reads the instrument list
rather than parsing the client's
PrintingConsoleimplementsOperatorConsoleas the legacy coloured stdout lines.- Each line reaches the log when printed, terminal or not:
main()sets stdout to line buffering before anything else (ADR 0026). - Its
rejectedprints one red line for anInvalidSignalor aRefusal, using the same "found, expected" shape for both. - Webhook text in that line is escaped with
reprand cut after 40 characters. - Its
order_rejectedprints one red line for anOrderRejected, with the broker's reason escaped the same way and cut after 160 characters. - Its
still_closingprints one red line with the open positions, the whole seconds since the first close request, and that later signals wait. - Its
closedprints one green line with the whole seconds from the first close request to the count that listed none, and hands it on like a red line (ADR 0028). - Its
broker_failedandbot_failedprint one red line each with the symbol and the exception's type, never its text. - Every red line goes through
_alert, which prints it and hands its text, without colours, to thenotifyit was built with: the notifier's, orno_notificationwhen Telegram is off (ADR 0027).
- Each line reaches the log when printed, terminal or not:
shownescapes a value from outside withreprand cuts it, for the console's lines and Telegram's error descriptions alike.telegram_from(telegram) reads the two Telegram settings, both or neither, and checks the token's form before it goes into a URL.TelegramChatsends one plain-text message throughurlliband returns aSendFailurethat says whether to try again; nothing it returns holds the token.urlopenis an argument with no default. It is the adapter of theChatport, whichnotifierdeclares.BackgroundNotifier(notifier) queues each message, with the time it was logged, up to 100 lines, for one daemon thread. A line that does not fit is dropped, and one count waits in the queue in its place, growing with each later drop and taking no line's slot (ADR 0029).Delivery(delivery) tries a message three times, waiting 2 s and 10 s or Telegram'sretry_afterup to 10 minutes, marks a message a minute late or more, and returns the report of one it could not send. It begins no try once the notifier has stopped. The notifier prints that report, in a red line that is never sent itself, unless the stop has counted the message; a stop still waiting waits for that print.end(seconds)sets the stop's deadline;stop()waits for the queue until then, and at least the floor, then reports the lines it loses and a dropped count the chat has not heard of, and ends the thread. One condition guards the queue, the message being sent, the count and the stop.SystemClockimplementsClockovertime.monotonicandtime.sleep. The monotonic clock, because the wall clock can step after an NTP correction or a manual change (ADR 0022).create_app(webhook) is the inbound HTTP adapter. It serves the webhook path, splits the body into lines and starts one thread per request. It serves nothing else: no OpenAPI schema and no docs pages, because the schema would name the secret path (ADR 0011). It redirects nothing: a path one slash away answers404, because the redirect pointed senders at plainhttp://(ADR 0013). It answers200once the thread has started, without waiting for it, and starts the thread last, so the bot answers no5xx, which TradingView would send again, once a signal is on its way (ADR 0023).server_log_config(server_log) is uvicorn's default log settings with an access line that keeps the client and the status but not the request line, which holds the secret path. Only the documentedfmtchanges, so no code reads uvicorn's internal log records. It sits in a module of its own because the app does not know which server runs it (ADR 0016).SignalHandlerruns one request's lines. It parses them before the lock and runs a valid signal inside it.- A rejection or a refusal gets one operator line.
- A broker failure gets one red
Broker failed:line, then is re-raised as the client's own exception, so the webhook thread fails as before. - Any other exception from the use case gets one red
Bot failed:line, then is re-raised as it was.
ascii_alertsholds the console's colours and the startup banners, andwebhook_pathmakes the random path for--url generate, fromsecrets(ADR 0012).secret_filereads the filepassword_fileortelegram_token_filenames, at most 1025 bytes, and checks the bytes in a function with no I/O; each message names the setting. An adapter module rather than a port: only the composition root asks for a secret (ADR 0024, ADR 0027).
Composition root¶
tradelocker_bot/composition_root.py is the only module that knows every
layer (ADR 0010).
main()reads the settings, prints the banners, logs in, builds the app and starts the server, in the order the startup diagram shows.parse_argsreads the settings from the environment variables the image is started with. An option of the same name on the command line replaces its variable. Each variable the command line does not replace becomes--name=valueahead of it, so one parser checks both sources. The password is read only from the environment, and--passwordis refused without its value, because the host's process list shows every command line. Unknown or shortened arguments are refused without being printed (ADR 0018).password_fromtakes the password from exactly one of two sources: the filepassword_filenames, such as a Docker secret, which keeps it out ofdocker inspect, or thepasswordvariable. Both set stops the bot, as does a file that is not one line of UTF-8 text of at most 1024 bytes; one trailing line ending is dropped and nothing else. The adaptersecret_filereads the file and checks its bytes. No message prints the content (ADR 0024).start_notifierstarts Telegram's notifier whentelegram_fromgave settings, and registers itsstopas an exit function, which Python runs once the webhook's threads have ended.mainhands the banners, the login and the server tolog_in_and_serve, with the notifier'snotifyorno_notification, and in afinallygives the queue 5 seconds from that moment (end), however it ends. The stop waits at leastSTOP_FLOOR_SECONDS, 2, even when those ran out orendnever ran (ADR 0029). A failed login is sent asLogin failed:before its exception leaves. Both Telegram settings come only from the environment (ADR 0027).- It creates the one lock that every request shares.
webhook_urlchecksurlas the settings are read:generateor a path that starts with/and has no{or}, so the route is one path, not a pattern, and no?,#or%, so a sender reaches it as typed. Anything else exits with status2, like any bad setting, and the message leaves the value out (ADR 0014, ADR 0015, ADR 0020).build_signal_handler(client, lock, clock, notify)builds the console, the broker adapter, the use case and the handler once, at startup. The characterization tests build theirs through the same function, with a fake clock that records each pause andno_notification; neither has a default, so no test can get the real clock or Telegram by leaving it out.main_without_ssl.pyimportsmainand calls it, and does nothing else.
Decisions¶
| ADR | Decision |
|---|---|
| 0001 | Migrate step by step, behind characterization tests |
| 0002 | CI quality gates and image publishing |
| 0003 | Publish the image with the workflow token |
| 0004 | A flat tradelocker_bot package next to the legacy entrypoint |
| 0005 | Execute-signal use case behind broker and console ports |
| 0006 | Broker failures as a Result |
| 0007 | Lock every runtime dependency |
| 0008 | Validate the whole signal before any broker call |
| 0009 | Refuse what the broker rules out before closing anything |
| 0010 | Inbound webhook adapter and a composition root |
| 0011 | Serve no API docs, so no page names the webhook path |
| 0012 | Generate the webhook path with secrets |
| 0013 | No trailing-slash redirect on the webhook |
| 0014 | Refuse a webhook path without a leading slash |
| 0015 | Refuse braces in the webhook path |
| 0016 | Hide the request line in the access log |
| 0017 | Override the broker client's pins on vulnerable packages |
| 0018 | Read the settings from the environment, not the command line |
| 0019 | Pin the base image by digest |
| 0020 | Refuse ?, # and % in the webhook path |
| 0021 | Report a rejected order in one line and place it once |
| 0022 | Pace the close loop on a clock and say when a close takes a minute |
| 0023 | The webhook's answer acknowledges receipt, not the outcome |
| 0024 | Read the password from a file |
| 0025 | Run the broker client at info, and name the account in the bot's own line |
| 0026 | Write the bot's output line by line, with or without a terminal |
| 0027 | Send the operator's red lines to Telegram, off the trading path |
| 0028 | Say when a close that took a minute ended |
| 0029 | Tighten the notifier's stop and its dropped count |
| 0030 | Gate the test coverage, and state the floor on the README |
| 0031 | Publish the documentation on GitHub Pages |