The SIA Is Not a Chatbot with Architecture: It Is a Platform with Intelligence
When someone asks me what the difference is between a product that "uses AI" and a product that "is intelligent," I respond with architecture.
Any system can call an OpenAI endpoint. What separates a prototype from a production platform is what lies between the user's message and the generated response. This is where architecture shows its value, or its absence.
The SIA was designed to be an intelligent service platform with real agentic capability. Not a wrapper for LLM with a chat interface. This required a series of architectural decisions that I will detail here, explaining the reasoning behind each one.
Why modular monolith, not microservices from the start
The first decision I had to make was about the overall structure of the system. And the answer was a modular monolith with a hexagonal core.
This choice goes against the instinct of those who have been exposed to a lot of talk about microservices. The standard narrative says that modern systems should be born distributed, with each capability in its own service. In practice, this approach has an operational complexity cost that early-stage projects rarely manage to absorb without detriment to development speed and product quality.
Microservices solve scaling and team problems. At the beginning of SIA, the problem is product-related: understanding the domain boundaries correctly before distributing them. When you distribute a poorly understood domain model, you also distribute the errors. And distributed errors are much harder to fix than errors contained in a monolith.
The modular monolith of SIA keeps the modules with clear internal boundaries: conversations, knowledge, workflows, decisions, and auditing. Each module has its own logic, its own use cases, its own rules. But they all share the same deployment process. This simplifies deployment, facilitates the refactoring of boundaries as domain understanding matures, and still allows for extracting microservices in the future when there is a real technical need, not anticipated.
The decision to extract a service should be guided by scaling pressure or team autonomy, not by preemptive architecture.
The hexagonal core as domain protection
Within the monolith, the core of SIA follows hexagonal architecture. This is not an aesthetic choice. It is the mechanism that prevents the business domain from leaking into infrastructure details.
The Domain Layer of SIA concentrates service rules, conversation flow, guardrails, policies, and validations. These rules represent the business knowledge of the product. They define how SIA should behave, what is allowed, what needs human approval, and what should be escalated.
This core knows nothing about databases. It does not know which LLM is in production. It does not know the Redis schema or the Qdrant endpoint. It knows contracts, expressed as ports, and expects concrete implementations to be provided from the outside.
Above the core is the Application Layer, responsible for SIA's use cases. It orchestrates the flow of a request: it receives the input, calls the domain with the correct data, requests external capabilities via ports, and returns the result. The Application Layer knows that there are ports. It does not know what is on the other side of them.
At the edge of the system, the Adapters implement these ports with concrete technology. The database adapter writes to Postgres. The cache adapter talks to Redis. The queue adapter publishes to RabbitMQ or SQS. The AI adapter calls the LLM Gateway. Each adapter is a boundary between the domain and the external world.
This separation has direct practical consequences. I can test the core of SIA completely without a database, without Redis, without LLM. Domain tests are fast, deterministic, and do not depend on running infrastructure. When a business rule needs to change, the impact is contained within the core. When technology needs to change, the impact is contained within the adapters.
The BFF/API Gateway as the first line of control
SIA operates with multiple entry channels: Web, WhatsApp, external API, and administrative panel. Each channel has different characteristics in terms of protocol, payload format, authentication requirements, and usage patterns.
Putting all this diversity directly into the Application Layer would create an entry code full of conditionals and channel-specific transformations. The BFF/API Gateway solves this.
At the edge of the system, the BFF centralizes authentication, session control, and rate limiting before any request reaches the core. A message from WhatsApp, an external API call, and an action from the administrative panel all pass through the same control layer before becoming normalized domain events.
Rate limiting at this position is not just a performance issue. In an AI system, it is also a cost issue. LLM calls have a price per token. Without rate control at the entry, a poorly configured client or an automation attack can generate unexpected costs before any alert is triggered.
Centralized authentication at the gateway means that the domain never has to deal with JWT tokens, OAuth sessions, or API keys. When a request reaches the core, it already carries a resolved identity context. The domain operates on identities, not on credentials.
The AI layer as a set of external capabilities
This is the part of the architecture where design decisions have the greatest impact on the longevity of the product.
The AI layer of SIA is structured in two levels: AI Ports and AI Adapters. The ports are the contracts that the core and the application layer know. The adapters are the concrete implementations that no one inside the hexagon knows.
The AIOrchestratorPort is the entry point for complex agentic flows. When the domain needs to trigger a multi-step reasoning process, it calls this port without knowing whether there is a LangGraph agent, a CrewAI system, a custom flow, or a hybrid implementation on the other side. The decision about the agent orchestrator is an AI infrastructure detail, not a business rule.
The LLMPort abstracts access to language models. The concrete adapter can point to the LLM Gateway that routes between OpenAI, Claude, or other providers based on availability and cost. Switching LLM providers, migrating to a more economical model for certain tasks, or running a local model for sensitive data are decisions that happen in the adapter, never in the domain.
The EmbeddingPort and the VectorSearchPort abstract the RAG pipeline. The vector search adapter can point to Qdrant, Pinecone, or any other solution. The core knows it can request relevant context given an input. It does not know how that context is indexed, in which vector database, or with which embedding model.
The GuardrailPort deserves special attention. Guardrails in production are not just content filters. They implement the product's policies on what SIA can and cannot say, which topics must be escalated to humans, and which responses need review before being delivered. This is a critical business rule. The GuardrailPort ensures that this rule is applied consistently regardless of which model generated the response.
The EvaluationPort is what transforms SIA from a system that generates responses into a system that learns about the quality of what it generates. It connects the production flow to automatic evaluation pipelines that measure relevance, coherence, adherence to policies, and perceived quality. Without systematic evaluation, there is no way to know if the system is improving or degrading over time.
The agentic flow in production
The complete flow of a message in SIA goes through seven stages that clarify the separation between domain and intelligence.
The message arrives through the channel and passes through the BFF, where authentication and rate limiting are applied. The Application Layer receives the normalized event and enters the conversation module. The first AI port triggered is the intent classification: what is the user trying to do? With the intent classified, the system searches for context in the RAG via VectorSearchPort, retrieving relevant information from the knowledge base configured for that client or service domain.
With context and intent available, the AIOrchestratorPort is triggered when the flow requires more elaborate reasoning. The orchestrator can trigger external tools via AgentPort, such as queries to legacy systems, checks in external databases, or executing concrete actions. The generated response passes through the GuardrailPort before anything else. If the guardrail rejects it, the fallback flow is triggered. If it approves, the response is delivered.
The entire operation is recorded via ObservabilityPort: timestamp of each stage, latency per component, model and version used, documents retrieved by the RAG with their similarity scores, guardrail result, tokens consumed, and estimated cost. This data is not debug logs. They are the main input for the evolution of the system.
When this design makes sense
This level of architecture is not justified for any project. It makes sense when certain conditions are present simultaneously.
First, when there are strong business rules that need to be protected from technological changes. A service system with compliance policies, escalation rules, and operational guardrails needs this protection.
Second, when the product operates across multiple channels with different characteristics. The BFF layer and the entry adapters absorb this diversity without contaminating the core.
Third, when AI supports decision-making and execution, not just generates text. A system that only needs static responses does not need AIOrchestratorPort or EvaluationPort. But when agents need to trigger tools, check conditions, and take sequences of actions, the abstraction of the orchestrator becomes necessary.
Fourth, when traceability and auditing are requirements, not optional. In service products with real volume, knowing exactly what the system did, for what reason, and with what result is not a differential. It is a basic operational necessity.
What changes when you decide to evolve
The strongest argument for this architecture is not what it allows you to do today. It is what it allows you to change tomorrow without incurring prohibitive costs.
When a new language model becomes available with better cost-effectiveness for intent classification, the LLMPort already has the contract defined. Creating a new adapter that points to the new model takes hours, not weeks. The domain is untouched.
When the volume of conversations grows to the point where the workflow module justifies extraction as a microservice, the boundaries of the module are already defined internally in the monolith. The extraction is a deployment decision, not an architectural refactoring.
When a client demands that sensitive data does not flow to external providers, the VectorSearchPort and LLMPort allow pointing to private instances without changing a line of the domain.
Each of these changes, in a coupled system, would require surgery on the core of the product. In the architecture of SIA, each is an adapter decision.
The principle that does not change
AI technology will continue to evolve at a pace that no roadmap can accurately follow. Better models will emerge. Agent frameworks will change. Vector databases will evolve. Providers will enter and exit the market.
What cannot change at the same speed are the rules that define how SIA serves, what can be said, what needs human review, how conversations are managed, and how decisions are audited. This business knowledge needs stability.
The architecture of SIA was designed to ensure exactly that: that the core of the product is immune to changes in AI infrastructure, while the AI layer is free to evolve without compromising the operational stability of the system.
A modular monolith with a hexagonal core and a separate AI layer is not the simplest architecture to explain in a slide. But it is the one that delivers a product capable of operating in production, evolving without risk, and being maintained by a team that does not need to understand the entire system to work on any part of it.
This is what separates an AI product from an AI prototype.
Alexsander Valente is a software engineer and architect with 15 years of experience in production systems. He is the founder of Threeger, creator of SIA, and a professor of conversational agent development in the MBA program at Ibmec.
