DSA Shield
A commercial and credit intelligence platform that turns portfolio data, financial history, and Serasa records into explainable sales priorities.
DSA Shield began with an idea from DSA Tecnologia: build a protective layer between a company and its credit decisions. I was brought in to turn that idea into a product and developed the entire solution myself—from data architecture to business rules, interfaces, integrations, and artificial-intelligence features.
“Protection” here does not simply mean blocking sales. The goal is to prevent commercial effort and credit limits from being distributed without context. Shield helps a company identify which customers in its portfolio combine growth potential, relationship strength, margin, and financial health, so it can increase credit and sales attention where the evidence is stronger.
The product is still pre-commercial. The platform is implemented, but it does not yet have customers or production impact metrics. This article documents it as engineering work, not as a case study with results that do not yet exist.
The problem: information exists, decisions do not
A commercial analysis rarely depends on one table. Relevant data may be scattered across a legacy ERP, orders, invoices, receivables, credit limits, payment delays, external checks, and a sales team's informal knowledge.
The result is a context problem: one customer may buy heavily and pay poorly; another may have healthy credit but weak margin; a third may be growing without receiving proportional attention. Looking only at revenue, a bureau score, or overdue payments produces an incomplete picture.
Shield organizes this landscape into three layers:
- integration, bringing operational and external data into a consistent model;
- deterministic analysis, calculating risk, alerts, and commercial potential with inspectable rules;
- generative assistance, letting a person query and cross-reference that data in natural language.
This separation was deliberate. The language model is not the source of truth and does not decide by itself whether a company deserves credit. It interprets results returned by controlled tools; limits, scores, and restrictions still come from verifiable data and rules.
Product architecture
Shield is a full-stack application built with Next.js, React, and TypeScript. Server routes and actions contain the business logic; PostgreSQL stores the operational model, while Prisma provides typed access and migrations. The interface uses Tailwind CSS, Radix components, and visualizations built with ECharts and Recharts.
The data model connects entities that would otherwise be analyzed separately:
- customers, representatives, and economic groups;
- orders, items, products, and categories;
- invoices and receivables;
- credit limits, payment delays, and negotiations;
- Serasa query history and restrictions;
- monetization tiers and scores;
- users, roles, and audit records.
The application also includes JWT authentication, role-based authorization, and administrative operations executed on the server. Deployment is structured around Docker, migrations, and persistent PostgreSQL storage.
Bridging the legacy Oracle system
One of the most important pieces was building a reliable route from the legacy system into the new application. Migration scripts query Oracle, normalize customers, orders, invoices, receivables, and products, then populate the PostgreSQL model used by Shield.
The integration uses node-oracledb and Oracle Instant Client in Thick mode. The driver's official documentation (opens in a new tab) explains that this mode loads Oracle Client libraries and, on Linux, requires the library path to be configured before the Node.js process starts.1
The challenge was not merely opening a connection. Legacy systems carry their own conventions: different names and types, incomplete identifiers, heterogeneous date formats, and relationships that must be reconstructed. The migration layer had to turn that material into coherent entities without erasing its origin.
Serasa as history, not one isolated number
The Serasa integration does not reduce a company to one score. Its ingestion endpoint stores both a summary and the underlying components: refinancing records, financial defaults, overdue debt, legal actions, protests, returned checks, purchase evolution, previous inquiries, payment history, suppliers, and company partners.
The Brazilian company registration number, CNPJ, acts as the reconciliation key. A customer can be created from incoming data when absent; when it already exists, the new history is associated and relevant credit information is updated. Related writes run inside a Prisma transaction so a failure cannot persist half a report. Transactions provide precisely this all-or-nothing guarantee.2
History also makes it possible to distinguish bad data from stale data. Dedicated alerts flag low scores, restrictions, overdue receivables, expired limits, missing credit, and outdated Serasa reports.
Human responsibility remains essential: credit-bureau information supports analysis but does not replace a company's lending policy. Serasa's own material emphasizes that the final decision to grant credit belongs to the granting company.3
An explainable monetization score
“Monetization” in Shield means improving a company's ability to generate revenue from its existing portfolio. The system asks: which customers deserve more commercial attention, and where could a higher credit limit create room for additional sales without ignoring risk?
I implemented a 0–1,000 score built from nine dimensions:
| Dimension | What it represents |
|---|---|
| Purchase frequency | recurrence over the previous 12 months |
| Relationship years | continuity of the commercial relationship |
| Average price | the customer's average purchasing position |
| Revenue share | its share of total company revenue |
| Top buyer | relative position among the largest buyers |
| Growth | change against the previous 12 months |
| Payment delay | payment behavior |
| Margin | economic quality of sales |
| Serasa and restrictions | external score combined with negative records |
Weights, delay bands, participation limits, and penalties are configurable. Heavy aggregations run in SQL, and the result is materialized per customer instead of recalculating the entire portfolio whenever a screen opens. New scores are written in bulk inside a transaction.
This keeps the ranking auditable. A user can inspect the components that produced the result instead of receiving only an opaque label generated by AI.
Shield AI Advisor
The AI Advisor converts commercial questions into constrained queries over real data. The interface streams responses, while the backend selects Gemini when a Google key is configured and OpenAI as an alternative.
The model receives an explicit set of tools:
- retrieve a customer's financial and credit summary;
- calculate revenue for a period;
- find top-performing products;
- search the product catalog;
- inspect recent orders;
- rank customers by value or purchase frequency.
Each tool validates its arguments with Zod and executes a specific server-side query. The model can chain up to six steps to compare periods, inspect recent orders, and relate a commercial opportunity to the customer's financial health.
This pattern is known as tool calling: the model selects an available operation and supplies structured arguments, while the application controls what is actually executed.4 In Shield, that boundary matters. The AI does not receive an unrestricted SQL connection, invent scores, or modify credit limits; it works through small, typed, observable functions.
Examples of intended questions include:
- “How does this month's revenue compare with last month?”
- “Which high-potential customers also have late payments?”
- “Which products generated the most value in this category?”
- “Does this customer have available credit and a recent Serasa report?”
What this project demonstrates
Shield was not merely the implementation of a finished specification. The initial idea had to become a data model, configurable policy, integration pipeline, and decision experience. My responsibility covered that entire transformation.
The most interesting parts do not live in isolation: Oracle and Serasa make data available; the score turns those data into an explainable priority; AI shortens the distance between a business question and the queries required to answer it.
The next milestone is commercial rather than merely technical: put the system in front of real companies, observe how analysts and sales teams make decisions, and validate whether the weights, alerts, and tools reflect everyday work. Until then, Shield remains a functional product looking for its first production environment—and a complete record of how I turned an idea for credit protection into software.
Footnotes
-
node-oracledb, “Initializing node-oracledb” (opens in a new tab), Thin and Thick modes and Oracle Client loading. ↩
-
Prisma, “Transactions and batch queries” (opens in a new tab), guarantees and APIs for atomic operations. ↩
-
Serasa Experian, credit consultation and recommendation material (opens in a new tab), including the granting company's responsibility for the final decision. ↩
-
Vercel AI SDK, “Tools and tool calling” (opens in a new tab), tool definitions, input schemas, and controlled execution. ↩