Problems, decisions and functional products

The initial briefing was broad, ambitious and with no defined scope. The first thing I did was not write code: it was understand what was actually inside it. The document mixed at least four distinct products without clear separation. Before touching anything, I rewrote it separating the content into 4 independent business modules and 1 cross-cutting technical module (the RAG pipeline). I defined what could be built independently, what depended on what, and what fell outside the 4-month MVP.

The result was a 6-phase roadmap and a scope that, for the first time, could be estimated, prioritized and communicated. Throughout the project I documented 38 architecture and stack decisions, specifying what I chose, what alternatives I evaluated, why I discarded each one. More than mere bureaucracy, it was the methodology that allowed me to advance without losing technical coherence or context.

The original approach contemplated scraping. The first thing I did was validate whether there was something better. And there was: the official PLACSP feed, with monthly ZIP files in Atom/XML format. I designed the pipeline with two single-responsibility scripts. The JSONL file connecting them acts as a contract: if loading fails, nothing needs to be re-downloaded. On top of that, I implemented incremental synchronization so the alert engine always sees fresh data.

A decision that defined the project: store everything at ingestion, without filters. Applying selection only at the query layer avoided having to reprocess the historical data every time a business criterion changed.

The underlying problem was semantic. CNAE and CPV codes classify sectors, but don't capture well what a company actually does or what types of contracts it's interested in. The solution combines two signals: semantic embeddings generated from the company's activity description, and heuristics based on its CNAE codes and those of the tender. When both signals are available, they're combined with a weighted average. When only one is available, though less precise, the system still works and doesn't break.

The result is a matching engine that improves with every piece of data the user provides about their profile, and that doesn't depend on everything being perfectly filled in to deliver useful results.