Definition
Architecture and Interfaces Architecture and interfaces define the major components of a system, the responsibilities assigned to each component and the contracts that connect them. In AI software this includes isolating model calls, retrieval, prompts, tools, data pipelines, policy checks and human review behind explicit APIs so behaviour can be tested, observed, replaced and governed.
Architecture captures high-impact structural decisions: boundaries, components, integration, data flow, deployment and quality attributes. Architecture should make model replacement and workflow evolution possible.
API and contract design defines stable interfaces, schemas, validation, errors, idempotency and versioning. Tool contracts for agents are APIs and deserve the same discipline.
Engineering Mode
Architecture and interfaces are what make AI systems governable. Model calls, retrieval, tools, policies and storage should have explicit contracts, ownership and failure behavior. Design must expose what users can trust or correct. Build work favors replaceable components and typed boundaries. Operations monitor each boundary separately. The risk is coupling product behavior directly to a prompt or vendor API with no control points.
Evaluation check
Ask what observable evidence would show that this concept has been applied well in a real system, repository or learning exercise.
Real Example
A production RAG assistant often separates the chat UI, retrieval service, model gateway, policy checks and audit logging. Clear interfaces let teams test retrieval without the UI, swap model providers, enforce permissions centrally and explain which evidence supported a generated answer.
Related Concepts
Further study: Len Bass, Paul Clements and Rick Kazman, Software Architecture in Practice , and Martin Fowler, Software Architecture Guide .
