Enterprise Trading Platform

Architecture diagrams

Eight pages describing the platform you build over Sprints 3 to 11: one view of the whole system, one deeper design view, and one page for each of the six things a team is responsible for. Everything on these pages is drawn from the contracts in docs/contracts/ and from the service code, so a name you see here is a name you will type.

Read them in order. The block diagram tells you the shape of the system in ten seconds. The high-level design tells you how a request moves through it and where the trust boundaries sit. The service pages tell you what is inside each box, and each one is the page to have open while you are writing that service.

The whole platform

overview System block diagram Every component, every connection, labelled with protocol and direction. Start here. design High-level design Layers, the write path and the read path, trust boundaries, the operational and analytical split, and order placement end to end.

The six things you build

Java 21 · :8080 Trade REST API The write path and the read path. Holds the domain package and every extension module. Java 21 · health :8082 Trade Executor Consumes orders, prices the fill, settles it in one transaction, publishes the outcome. Runs the market-data poller on a schedule. NestJS 11 · :3000 Auth service Registration, login, refresh, current user. The only service that ever sees a password. Angular · :4200 Frontend Login, dashboard, order ticket, blotter. Holds the JWT and attaches it on every call. Python 3.12+ · DuckDB Analytics service Batch extract, transform, load into a star schema, and the dashboard that reads it. Kafka · :9092 Kafka event backbone Three topics, their keys, partitions and retention, and which service is on each end.

How to read these diagrams

One visual language runs through every page. Colour carries meaning and nothing else does, so a shape you recognise on one page means the same thing on the next.

Built by the teamOne of the six. You write it, test it and own it.

ProvidedAlready running or already written. Configure it, do not build it.

Data storeSomething on disk that survives a restart: PostgreSQL, the DuckDB file.

Kafka topicDivided into its real partition count. Messages, not rows.

HTTPA synchronous call. The caller waits for the answer.

JDBC and SQLA database connection. Rows in, rows out.

Kafka produce or consumeAsynchronous. The producer does not wait and does not know who reads.

Call out of the platformLeaves the compose network. Rate limited, and it can fail.

What the diagrams assume

The platform is five services and a broker the team stands up and owns, plus infrastructure that is handed to you. Two rules follow from that and they explain most of what you will see.

One language per service. Java in the Trade REST API and the Trade Executor, TypeScript in the auth service and the frontend, Python in the analytics service and nowhere else. A container that runs two runtimes is a container nobody wants to debug.

One place for each responsibility. One service accepts orders. One service executes them and calls the Fauxnance API. One service sees passwords. One store answers "what is my balance now" and a different store answers "what did the desk trade last quarter".