Brutus

One AI service for a whole product suite, behind ports rather than SDK calls

A centralised AI hub serving the products around it: marketing copy, WhatsApp and SMS template mapping, sender-ID compliance, and fraud and phishing scanning. Built as a modular monolith on hexagonal architecture so the model provider is an implementation detail rather than something spread through every codebase that wants to generate text.

StatusTask pipeline, RAG and safety scanning in use; the agentic planning layer is the newest and least proven part.

Built for: Ballo Innovations
My role: Architecture and implementation.
When: 2026 — present

NestJS
TypeScript
Groq
Llama 3.1
PostgreSQL
Hexagonal architecture
RAG
Embeddings

Used inside BalloAds

01The engineering

What made it hard

The problems worth reading about. Everything else in this system was ordinary work.

01
The alternative was every product calling a model SDK directly. That spreads prompt logic, provider credentials, cost accounting and safety rules across four codebases, and guarantees they drift. One hub behind a port means a provider change, a prompt fix or a new guardrail lands in one place.
02
Provider selection is explicit routing rather than a hardcoded client, for the same reason the retrieval demo on this site ranks providers: the cheapest acceptable model should answer, and the system should say which one did.
03
Safety scanning is a standalone task rather than a mandatory pipeline stage. Fraud and phishing detection is a real capability with a real cost, and forcing every copywriting request through it would have made the common path pay for the rare one.
04
Generation is grounded through a retrieval layer over company profiles, brand documents and past campaigns, because the failure mode that matters for marketing copy is not a clumsy sentence — it is a confidently invented product claim going out over SMS to a real customer list.

02Numbers

What it measures

Each figure says where it came from, so you can judge how much weight to give it. Some are measurements and some are chosen thresholds; the basis line tells you which.

6
Task types exposed: 6
Core domains behind ports: 0
Model SDKs in consuming products

Write-up

The longer version

Why a hub rather than a library

A shared library would have solved the duplication and none of the operational problems. Prompts change more often than releases, provider outages need a response measured in minutes rather than deploys, and someone has to be able to answer "what did we spend on AI last month, and on what". A library gives you one copy of the code and four copies of the runtime behaviour.

Putting it behind a service boundary also made the cost accounting possible at all. Usage and spend are attributed per consuming product and per task type, because "AI costs" as a single line item is not a number anyone can act on.

The architecture, and what it bought

Hexagonal was not a stylistic choice. The volatile parts of this system are exactly the ones at the edges — which model provider, which messaging channel's template format, which product is asking — and the stable part is the middle: what a task is, what context it gets, what safety means. Ports and adapters put the churn where churn is cheap.

The concrete payoff: adding a consuming product is an adapter, and changing model provider does not touch task logic.

What is least proven

The agentic planning layer — multi-step workflows with a tool registry and human approval gates — is the newest part and the part I would be most cautious about claiming. The task-oriented paths have been exercised by real campaign traffic. Planning has not, to the same degree, and an agent that plans badly fails in more interesting ways than a copywriter that writes badly.