A technical case study of a self-hosted AI safety gateway: how it validates AI output before delivery, routes uncertain cases to human reviewers, and preserves auditability for every decision.
Technical Overview
The system is a self-hosted AI safety gateway: an API service that inspects what an AI agent produced and returns a Pass, Flag or Block ruling before that output reaches a customer, gets published, or triggers an automated action.
It sits between the AI application and everything downstream of it. The application keeps generating responses with whatever model or agent framework it already uses. Before acting on a response, it submits the output and its original context to the moderation API, then branches on the structured ruling that comes back.
Three components do the work:
- Moderation engine. Runs up to eight safety checks under the policy assigned to the calling AI source.
- Severity-based decision engine. Reduces the individual check results to one ruling, with a confidence score and supporting evidence.
- Human review workflow. A web dashboard and a Flutter mobile app for flagged and blocked cases, backed by an audit trail of rulings, evidence, policy versions and reviewer activity.
Source basis: statements about platform behaviour come from the product’s feature specification. Passages labelled “Architectural reading” are analysis of what the documented design implies. This document adds no technologies, metrics or implementation details the specification does not state.
The Engineering Challenge
An AI response is a proposal, and the engineering problem is deciding, output by output, whether that proposal is safe to turn into an action. Placing a validation layer on that path raises six constraints at once.
The failure modes differ in kind
An answer can be fluent and still unsupported by its context. It can contradict that context, break an operational rule, expose personal data, propose a sensitive action, violate a coding convention, miss the brand’s tone, or route a case to the wrong place. A single composite score would hide which dimension failed, so the layer needs separate checks whose results stay individually visible.
Judgement depends on context
Hallucination and contradiction can only be assessed against something. The API contract therefore has to carry the original context alongside the output.
Rules differ by application
A customer-support agent and an internal coding assistant do not share a risk profile. One global rule set would over-block one application or under-protect the other, so policy has to be scoped per AI source.
Failing safely
Once the layer sits in front of an action, “could not check” must not behave like “checked and fine.” A timed-out evaluation or an unverifiable claim needs a defined outcome that does not let unchecked content through.
Not every decision should be automated
Some outputs are ambiguous, and some are serious enough to need a person. The layer needs a ruling the application can branch on, plus a review path that does not depend on reviewers also being system administrators.
Decisions must be traceable
Weeks after an output was blocked, someone will ask why. Answering requires the check results, the evidence, the policy and its version at the time, and a record of who reviewed the case and what they decided.
Why a Dedicated Guardrail Layer?
AI generation is not AI execution. A model produces text, and that text becomes a business event only when something acts on it: a message sent to a customer, a post published, a record updated, a case routed. Treating the two as one step is where most of the risk sits.
The model generates a proposal. The application decides whether that proposal reaches a user or triggers an action. When generated output flows straight into delivery, that decision is made implicitly by the code path, with no separate place to apply rules, record why, or bring in a person.
A guardrail layer separates those responsibilities. The model proposes. The guardrail evaluates the proposal against a policy and returns a ruling. The application enforces that ruling at its own point of delivery or action. Reviewers handle the cases that automation should not settle alone. Each responsibility can then change on its own schedule: a new model, a tighter threshold, or a different reviewer team does not require rewriting the others.
Architectural reading: keeping this layer outside the AI application also means the check does not share the failure modes or release cycle of the application it constrains, one policy engine, reviewer queue and audit store can serve several AI products, and a policy change does not require redeploying the application. The documented design follows this separation: a structured ruling the application branches on, policy scoped per source, a defined path to human review, and a retained record of every decision.
Solution Architecture
The architecture is one request path with a review path branching off it. Every output is identified by source, evaluated under that source’s policy, reduced to one ruling and recorded, and the cases that need a person move into a separate reviewer workflow.
| Layer | Role |
|---|---|
| 1. External AI application | Generates a response or proposed action, and submits it with its context instead of acting on it directly. It is outside the platform and unchanged by it. |
| 2. Moderation API | Accepts the output and context and returns a structured, machine-readable ruling the application can branch on without parsing prose. |
| 3. AI source and policy selection | Each connected application is a registered AI source with its own API credentials. The policy assigned to that source, with its enabled checks, thresholds and version, is applied. |
| 4. Safety checks | Enabled checks run independently, disabled ones do not run, and each produces its own result, kept as an individual record. |
| 5. Severity decision engine | Reduces the results to one ruling under a safety-first rule: the most severe ruling wins. |
| 6. Pass / Flag / Block | Returned to the application with confidence and evidence information. |
| 7. Application branching | Passed content continues, flagged content can enter review, blocked content is prevented from continuing. The platform issues the decision and the application enforces it. |
| 8. Human review | Flagged and blocked cases can be routed to reviewers on web or mobile. The reviewer role needs no administrative access. |
| 9. Audit and evidence | Each case retains its ruling, check results, confidence, evidence, policy and version, reviewer information and decision history. |
The API provides the primary integration surface between connected AI applications and the moderation platform.
Architectural reading: the specification states that each source has its own credentials and that policy, thresholds and case history are kept per source. It does not describe the lookup mechanism, but the credential is the natural point at which a request is tied to a source. Because credentials are per source, one application’s access can be managed or revoked without touching another’s. The specification does not describe the storage technology behind the audit record, so this document does not either.
AI Moderation API Workflow
The workflow has ten stages, and each has one responsibility. That separation is what makes the final ruling explainable after the fact.
| # | Stage | Responsibility |
|---|---|---|
| 1 | AI agent generates a response | Produce a candidate response or proposed action |
| 2 | Application sends output and context | Submit the output with the context needed to judge it |
| 3 | Moderation system identifies the policy | Resolve the AI source and its assigned policy and version |
| 4 | Enabled checks execute | Evaluate the output independently under each enabled check |
| 5 | Individual check results are generated | Record one result per check, with evidence |
| 6 | Severity logic determines the ruling | Reduce results to the most severe applicable ruling |
| 7 | Structured response is returned | Hand the ruling, confidence and evidence to the application |
| 8 | Application branches | Continue, hold or stop according to the ruling |
| 9 | Human review, if required | Let a reviewer inspect evidence and decide |
| 10 | Evidence and history are retained | Preserve ruling, policy version and reviewer activity |
The specification defines what goes in (AI output and relevant context) and what comes out (a ruling with confidence and evidence information). It does not publish field names, so none are invented here.
Figure 1. Moderation request sequence, from the AI agent’s draft to the recorded reviewer decision.
Eight Safety Validation Modules
The platform splits “is this output safe to use” into eight separate questions, each answered by its own configurable check. Every check receives the AI output and its context under the selected policy and returns its own result.
The specification does not name the algorithms or models behind the checks, and it does not assign a fixed ruling to each check. Architectural reading: how a check’s result becomes Pass, Flag or Block follows from the threshold configured for that check in the policy, and the decision engine then applies the severity rule across all results.
1. Hallucination Detection
Purpose. Catch fabricated or unsupported statements before a customer or downstream system treats them as fact.
Input. The AI output and the context supplied with it.
Validation logic. Compares the generated answer against the supplied context and looks for claims the context does not support. Where a claim cannot be adequately verified, the check reports that instead of assuming it is correct.
Decision impact. Unverifiable results can be sent for review instead of automatically passing.
Example. A support agent states a refund window, but no supplied context mentions one. The result cannot be verified and the case is routed for review.
2. Contradiction Detection
Purpose. Stop responses that conflict with known information, or with themselves, from driving automated decisions.
Input. The AI output and the available context.
Validation logic. Looks for statements that conflict with the context and for inconsistent statements within the output itself.
Decision impact. A detected conflict contributes a result to the severity decision, and passing checks elsewhere cannot cancel it.
Example. The context records a plan as active, and the response tells the customer it has been cancelled. The check records that conflict.
3. Policy Violation Detection
Purpose. Enforce an organization’s operational rules on what an AI agent may say or do.
Input. The AI output and the rules configured in the policy assigned to the calling source.
Validation logic. Evaluates the output against the configured policy and applies the policy’s threshold to decide how serious a departure is.
Decision impact. Thresholds are set per policy and per check, so the same wording can be acceptable for one source and unacceptable for another.
Example. A support policy prohibits a certain kind of commitment, and a response makes it. The check returns a result reflecting the violation.
4. PII Leak Detection
Purpose. Reduce accidental disclosure of personally identifiable information.
Input. The AI output about to be delivered or published.
Validation logic. Looks for possible exposure of personally identifiable information, as a privacy layer at the point where content is about to leave the workflow.
Decision impact. Exposure of sensitive user information is a serious failure category, and a PII result that calls for blocking cannot be outvoted by passes elsewhere.
Example. An agent answering a ticket includes another customer’s contact details. The check reports possible exposure before the reply is sent.
5. High-Risk Action Detection
Purpose. Stop questionable AI decisions from proceeding automatically when they could trigger a sensitive action.
Input. The AI output or proposed action.
Validation logic. Identifies outputs capable of triggering potentially sensitive actions.
Decision impact. Risky outputs are routed for review, so a proposal for a consequential action becomes a case a person sees instead of an action the system takes alone.
Example. A workflow agent proposes an action with business consequences. The ruling stops automatic execution and sends the case for review.
6. Code Convention Validation
Purpose. Keep AI-generated code consistent with the rules a team has configured.
Input. The AI-generated code and the conventions defined in the policy.
Validation logic. Evaluates the code against the configured conventions and detects output that does not satisfy the required coding rules.
Decision impact. Relevant for code-producing sources, and can be disabled for sources that do not generate code, since checks are enabled per policy.
Example. An internal coding assistant returns a function that ignores a configured naming or structure rule, and the check reports it as non-conforming.
7. Tone and Brand Safety
Purpose. Hold generated content to a brand’s communication standards.
Input. The generated content and the brand expectations configured for the source.
Validation logic. Evaluates tone and detects responses inconsistent with the configured brand expectations.
Decision impact. Evaluated per policy, so a formal support channel and an informal marketing channel can use different expectations. Results over time feed the tone trend analytics.
Example. A customer-facing agent replies in a register the brand has configured as unacceptable. The check records a tone result.
8. Routing Validation
Purpose. Check AI workflow decisions before downstream processing acts on them.
Input. The AI response or workflow decision, together with where it is being routed.
Validation logic. Evaluates whether the response is being routed appropriately.
Decision impact. A failed routing result keeps a mistaken workflow decision from reaching the downstream step as if it were sound.
Example. An agent sends a case to a destination that does not fit its subject. The check reports the routing as inappropriate before the downstream step runs.
Policy Architecture
A policy is the unit of configuration that decides how strictly each AI application is validated, and every moderation case is evaluated under exactly one.
The documented policy model has these properties:
- One policy per AI application, assigned by AI source, so different agents can have different policies.
- Per-check enable and disable. A policy decides which of the eight checks run.
- Independent thresholds. Each check has its own threshold.
- Version awareness. Policy records are versioned, and each case records which version evaluated it.
Why policy isolation matters technically
| Dimension | Customer-support AI | Internal coding assistant |
|---|---|---|
| Main exposure | What customers read and what actions follow | What code reaches a repository or team |
| Checks likely to matter | Hallucination, PII leak, tone and brand, high-risk action, routing | Code convention, policy violation |
| Checks likely switched off | Code convention | Tone and brand |
| Typical consequence of a miss | A customer sees wrong or private information | A convention is broken in generated code |
The table is an illustrative contrast, not a set of product defaults.
Isolation gives three engineering benefits. Editing one policy changes behaviour only for the sources assigned to it, so a strict threshold for one application is not forced onto another. Because the policy version is recorded per case, a past ruling can be understood against the rules that applied then, not the rules as they stand today. And the documented controls include policy isolation between AI applications, so one application’s configuration is not shared with another.
Severity-Based Decision Engine
The decision engine turns many independent check results into one ruling by taking the most severe one, so a serious failure cannot be diluted by passes elsewhere.
The documented safety-first model rests on six statements:
- Individual checks are evaluated separately.
- Serious failures cannot be cancelled out by successful checks.
- The most severe ruling determines the final result.
- A single Block result can block the overall output.
- Unverifiable results can be sent for review instead of automatically passing.
- Model timeouts can result in Flag status rather than allowing unchecked content through.
A deterministic decision layer
The reduction step is rule-based. Given the same set of check results, it produces the same ruling, with Block outranking Flag and Flag outranking Pass. Averaging or voting would behave differently: nine clean results could lower the weight of one severe failure, and taking the most severe ruling removes that failure mode by construction.
That determinism applies to the decision layer. The specification mentions model timeouts, which indicates the evaluations themselves involve a model, and it does not claim those evaluations are identical from run to run.
Decision table
| Check results | Final decision | Reason |
|---|---|---|
| All checks pass | Pass | No blocking or flagging condition |
| One or more checks require review | Flag | Human review required |
| Any single check returns Block | Block | Safety-first enforcement |
| Block, Flag and Pass results together | Block | The most severe ruling determines the result |
| A result cannot be verified | Flag | Unverifiable output is sent for review, not passed |
| Validation cannot complete, such as a model timeout | Flag where applicable | Avoids letting unchecked content through |
The failure semantics matter as much as the happy path. A timeout does not silently become a pass, and it does not become an automatic block either. It becomes a Flag, which puts the case in front of a person.
Evidence and Audit Architecture
Each moderation case can retain enough evidence to answer, after the fact, why an AI response was approved, flagged or blocked. The documented record has eight elements, and each answers a different question an investigator will ask.
| Retained element | Question it answers |
|---|---|
| Final moderation ruling | What was decided: Pass, Flag or Block? |
| Individual check results | Which checks passed, and which one drove the outcome? |
| Confidence information | How certain was the evaluation? |
| Evaluation evidence | What did the evaluation rest on? |
| Policy used | Which rule set judged this output? |
| Policy version | Which revision of that rule set was in force at the time? |
| Reviewer information | Which person reviewed the case? |
| Decision history | What happened to the case, in what order? |
What this makes possible
- Debugging. An engineer can see which check produced a ruling and on what evidence. A recurring false flag can be traced to a specific check and threshold.
- Incident investigation. The history shows what the platform ruled, under which policy version, and whether a person intervened.
- Accountability and explanation. Reviewer information makes each human decision attributable, and the evidence lets a team say why something was blocked, not only that it was.
- Reconstructing context. Policy, version, check results and evidence together rebuild the conditions of a decision, including after the policy has changed.
Policy version is the element most easily overlooked. Without it, a ruling from last month can only be judged against today’s rules. The specification does not describe the storage layer and does not claim regulatory compliance, and neither does this document.
Human-in-the-Loop Architecture
Human review is the defined destination for every case the automated layer should not settle alone, which makes it a safety mechanism and not an administrative extra.
- Flagged cases enter the review workflow, and the application holds the content while a reviewer decides.
- Blocked cases are prevented from continuing and can also be reviewed, so a block is something a person can examine.
- Evidence and check results are available to the reviewer, who sees which individual checks fired and not just the overall ruling.
- The decision is made by a human, and the reviewer who made it is recorded.
The specification documents the review outputs as the recorded decision and reviewer identity. It does not describe a callback that sends a reviewer’s decision back to the application, so application-side handling of that decision is outside what this document asserts.
Architectural reading: the engine’s two fail-safe behaviours, unverifiable results going to review and a model timeout yielding Flag, both assume a review path exists. Without one, those rules would have no destination. Because the reviewer is recorded and reviewer access is separate from system configuration, a reviewer can resolve cases without altering the policies or thresholds that produced them. The same draft-then-human-sign-off principle appears in regulated-document tools such as Zipprr’s AI Lawyer, where AI output is a starting point and a person makes the final call.
Role-Based Access Architecture
Three actors interact with the platform, each through a different channel and with a different scope of authority.
| Actor | Access channel | Responsibilities |
|---|---|---|
| Administrator | Administration dashboard | AI sources, API credentials, policies, thresholds, users and reviewers, branding, webhooks, analytics, system configuration |
| Reviewer | Web reviewer dashboard and mobile app | Reviewing flagged and blocked cases, examining evidence, making human moderation decisions |
| Connected AI application | API credentials | Submitting outputs and context programmatically, receiving structured rulings |
Reviewer access is intentionally separated from administrative configuration. In engineering terms, that gives least privilege (moderation staff get cases and evidence and nothing that changes system behaviour), independence between a ruling and its review, and contained exposure, since a reviewer account on a mobile device carries no ability to change credentials, policies or webhooks. Moderation capacity can also grow by adding reviewers without widening the group that holds configuration authority.
Multi-Application and AI Source Architecture
One moderation installation can govern several AI applications, because the unit of isolation is the AI source and not the installation. Each connected application is registered as its own source, with individual API credentials, a separate policy with its own enabled checks, independent thresholds, source-specific configuration, and case tracking by source.
| Kept separate per source | Shared across sources |
|---|---|
| Credentials | Moderation engine and decision logic |
| Policy and thresholds | Reviewer workflow |
| Case history by source | Administration, analytics and branding |
An organization running a support agent, a sales assistant and a coding assistant gets one reviewer queue, one audit record and one place to manage access, while each agent is still judged by its own rules. Revoking one application does not disturb the others. Assistants built on products such as Zipprr’s AI Chat or WhatsApp Automation are examples of the kind of source that fits this pattern. The specification names no specific integrations.
Webhook and Event Architecture
Webhooks let the platform push moderation events to other systems, so a flagged or blocked result can start work elsewhere without anyone polling for it.
The documented capability covers flagged-result and blocked-result notifications, external workflow integration, signed requests verified with HMAC SHA-256, and retry support with backoff handling when queue workers are configured. The specification names five integration categories (CRM systems, support platforms, monitoring systems, internal dashboards and workflow automation tools) and no specific products.
Figure 2. Webhook delivery flow: a Flag or Block event is queued, signed and delivered, with backoff and retry when delivery fails.
Request signing
Each webhook request is signed with HMAC SHA-256, so the receiving system can verify the signature before acting. The specification does not state header names or payload format, so those are left to the product documentation.
The practical value is in what the receiver can do next: open a ticket in a support platform, update a CRM record, raise a monitoring alert, or trigger an automation.
Queue-Based Processing
Queue workers move webhook delivery and retries out of the request path, so an unreachable external system does not delay or break moderation. The documented benefits are background processing, more reliable external notifications, retry handling, and backoff between failed attempts.
Architectural reading: the queue separates two concerns with different failure characteristics. Producing a ruling depends on the platform and its checks. Delivering a notification depends on someone else’s system, which may be slow, down or rate-limited. With the two decoupled, a CRM outage affects notification timing and not the safety decision the application is waiting on.
The specification ties backoff to queue workers being configured, so an operator who wants delivery retries has to run them.
API Security Architecture
The documented security controls are narrow and structural: they limit who can call the API, who can receive events, and who can change rules.
| Control | What it protects against |
|---|---|
| Separate credentials per connected AI source, with manage and revoke | One compromised or retired application exposing or disabling the others, and continued access by an application that should no longer have it |
| Signed webhooks with HMAC SHA-256 verification | Forged or tampered event notifications reaching external systems |
| Policy isolation between AI applications | One application’s rules or thresholds being altered, or inherited, by another |
| Reviewer and administrator permission separation | A reviewer account being used to change credentials, policies or webhooks |
Inbound calls are tied to a per-source credential, outbound events are signed, and inside the platform policy isolation and role separation keep configuration authority away from people and applications that do not need it. Controls beyond these are not documented and are not assumed. Because the platform is self-hosted, securing the infrastructure around it is the deploying organization’s job.
Web and Mobile Reviewer Architecture
The same review workflow is reachable from a browser and from a phone, so reviewers are not tied to a desk when a flagged output is waiting.
The web reviewer dashboard supports case management, evidence inspection, moderation decisions and the reviewer workflow.
The Flutter mobile application covers iOS and Android and is designed to provide reviewer functionality comparable to the web dashboard. Reviewers can review cases and decisions, examine flagged and blocked outputs, view supporting evidence, perform reviewer actions and receive push notifications.
A flagged output is often held while it waits for a decision, so the wait has a cost. A push notification for a new flagged or blocked case brings a reviewer to it without continuous dashboard monitoring, which makes review latency depend on when someone is told and not only on when someone is at a screen. Reviewer rights on mobile remain reviewer rights, with no administrative configuration access.
Technology Stack
The specification verifies a compact set of technologies, and this list contains only those.
| Layer | Technology | Role in the system |
|---|---|---|
| Backend | Laravel-based application | Moderation engine, API and platform logic |
| Administration interface | Filament 4 | Centralized configuration and analytics |
| Mobile reviewer app | Flutter, for iOS and Android | Case review on phones and tablets |
| Integration | REST and API-based architecture | How connected AI applications submit output and receive rulings |
| Mobile alerts | Push notifications | Telling reviewers about new flagged and blocked cases |
| Event delivery | Webhooks with HMAC SHA-256 signing | Verified notifications to external systems |
| Asynchronous work | Queue-worker support | Webhook delivery, retries and backoff |
The specification names no database, cache, hosting platform or model provider, so none appears here.
Administration Architecture
A dedicated administration interface centralizes everything that changes how the system behaves.
| Concern | What is managed |
|---|---|
| Applications | AI sources and their API credentials |
| Rules | Moderation policies, safety checks and thresholds |
| People | Users and reviewers |
| Integration | Webhooks and notifications |
| Identity and system | Branding and system settings |
| Insight | Moderation analytics |
Adding an AI application means registering a source, issuing credentials and assigning a policy, all from one interface. Tightening one application’s rules is an edit to one policy, and removing its access is a credential action, not a code change. Because configuration lives here and reviewers work in their own interface, the people who judge cases are not the people who tune the rules.
Analytics and Observability
The analytics in the administration area show how AI agents behave across rulings, checks and tone, which lets recurring problems be found instead of rediscovered case by case.
| Documented insight | What it can reveal |
|---|---|
| Moderation rulings over time | Whether an agent’s safety profile is improving or drifting |
| Pass, Flag and Block activity | The balance between clean output and output needing intervention |
| Check-level performance | Which individual checks are doing the work |
| Frequently triggered checks | A recurring weakness, such as repeated PII exposure or unsupported claims |
| Tone trends over time | Gradual movement away from brand expectations |
Read together, these point to causes. If one check fires repeatedly for one source, the likely fix is in that agent’s prompt, context or data. If a threshold produces many Flags that reviewers routinely clear, the threshold is a candidate for adjustment. The specification documents moderation analytics and does not describe infrastructure monitoring.
White-Label and Configuration Architecture
Branding is configuration, not code. The configurable elements are the platform name, logo, support email or address, and interface colour palette, and changes can propagate across the web interface, the mobile application and email communications.
Architectural reading: the specification says common branding changes do not require rebuilding the mobile app, which suggests the app reads its branding from platform configuration. It does not describe the mechanism.
Accessibility-aware status colours
Moderation status is the most important thing a reviewer reads on screen. The branding configuration therefore includes a safeguard: it can reject colour combinations where Pass, Flag and Block would become difficult to distinguish under simulated colour-vision deficiencies. A palette chosen for appearance could otherwise collapse three different rulings into similar colours. This is a configuration safeguard, not a formal accessibility certification.
Supporting capabilities
The platform also includes customizable error pages, a built-in live chat widget for support, and illustrated documentation with an extended PDF manual.
Notifications Architecture
Two human-facing channels carry moderation communications, and each suits a different kind of urgency.
- Email. Multiple configurable templates cover system communications, including moderation and account-related notifications, and carry the configured white-label identity.
- Push. Mobile reviewers are notified of new flagged and blocked cases, which supports time-sensitive review without watching a dashboard.
Machine-to-machine events travel separately, over signed webhooks. A held output only gets resolved once someone knows it exists, and push notification is what shortens that gap.
Installation and Deployment Workflow
Deployment is a guided, four-step web installer that configures the application without manual editing of configuration files in a normal installation. After a successful installation the installer closes itself to prevent unnecessary reuse.
The specification does not list the four steps or describe deployment infrastructure, so this document does not either. Architectural reading: a guided installer reduces the chance of a misconfigured moderation service, which matters because a misconfigured safety layer fails quietly, and a self-closing installer removes a setup surface from a running system that has no reason to expose one.
Testing Strategy
The software ships with an automated test suite covering the components that most directly shape moderation outcomes.
| Area covered | Why it matters |
|---|---|
| Moderation engine API | The ruling an application receives is what it acts on |
| Access gates | Role separation only holds if permission checks hold |
| Installation process | A correct first deployment is the base for everything else |
| Administration functionality | Policies, thresholds and credentials decide how strict the system is |
In a system where a moderation decision can stop or release downstream action, a regression is not cosmetic. Automated coverage gives developers a way to validate the system after deployment or customization. The specification states the coverage areas and gives no coverage percentages or CI details, so none are claimed.
End-to-End Technical Scenario
This walkthrough follows one AI customer-support reply through the platform, using only documented capabilities. It is a worked example and contains no measured results.
The setup: a support agent drafts a reply to a customer who asked about a refund. The agent could be any chat assistant, for example one built on Zipprr AI Chat, and the specification describes no specific integration. The reply states a refund timeframe that nothing in the supplied context confirms. The support policy for this source has all eight checks enabled.
| Step | What happens | Component |
|---|---|---|
| 1 | The AI agent drafts the reply. | External AI application |
| 2 | The application submits the draft and its context (the conversation and relevant records) with the support source’s API credential. | Moderation API |
| 3 | The source is identified, the customer-support policy assigned to it is selected, and its version is noted for the case. | Source and policy selection |
| 4 | Eight checks evaluate the draft independently. Seven report no issue. Hallucination Detection cannot verify the refund timeframe against the supplied context. | Enabled safety checks |
| 5 | The severity logic sees no Block and one result that needs review. The final ruling is Flag. | Decision engine |
| 6 | The API returns a structured Flag with confidence information and evidence pointing at the unsupported statement. | Moderation API |
| 7 | The application holds the reply. The case enters human review, reviewers can be alerted by push notification, and a webhook can notify an external support platform. | Application, notifications, webhooks |
| 8 | A reviewer opens the case on the web dashboard or mobile app and inspects the check results and evidence. | Reviewer workflow |
| 9 | The reviewer makes a moderation decision. | Human review |
| 10 | The ruling, check results, evidence, policy and version, reviewer identity and decision are retained. | Audit and evidence storage |
Two properties of this flow stand out. The unverified claim did not reach the customer, and it did not need a Block to be stopped, because unverifiable output is a Flag. And the reviewer saw more than a verdict: they saw which check fired and why, and weeks later the same record explains the outcome.
Engineering Decisions and Trade-Offs
This section is analysis. Each major decision in the design buys something specific and carries a cost that follows from it. The costs below are consequences of the documented architecture, not reported defects.
Centralized moderation versus embedded validation
A central API means several AI applications share one engine, one reviewer queue and one audit record. The trade-off is that the moderation service becomes a dependency of every connected application’s action path, so what an application does when it receives no ruling is a decision for that application’s design. The platform’s own rule for model timeouts, Flag over unchecked pass, shows the intended direction.
Automated decisions versus human review
Pass, Flag and Block give the application three clear branches while review preserves human judgement for uncertain or serious cases. The cost lands on reviewer capacity, since every Flag is work for a person. Thresholds and check-level analytics become the means of tuning how much reaches the queue.
Independent checks versus one composite evaluation
Independent checks keep each safety dimension observable and traceable. The cost is more individual results to reconcile, which is why the reduction rule is deliberately simple: the most severe ruling wins.
Policy isolation
Per-source policies let one application be tightened without touching another. The cost is more policies to maintain, which versioned records limit, since each case states which version judged it.
Evidence retention
Retained results, evidence, policy version and reviewer activity give debugging and investigation what they need. The evidence may itself contain sensitive content, because the outputs it describes can, so the evidence store deserves the same care as the data it describes. The specification does not describe retention periods or storage, so those are deployment decisions.
Webhook and queue architecture
Asynchronous delivery with retries and backoff keeps unreliable external systems from disturbing moderation, and signing lets receivers trust what arrives. The costs are operational: someone must run the queue workers, and because retries exist, a receiver may see the same event more than once and should tolerate that.
Technical Architecture Diagram
The diagram shows the request path and the review path for any connected AI application, with administration and event delivery alongside. Everything on it is documented behaviour.
Figure 3. Technical architecture and data flow. Pass: the application continues. Flag: human review. Block: the application prevents the downstream action, with review when required. The administration dashboard configures sources, credentials, policies and thresholds.
Technical Data Flow
Data moves in one direction through the platform, and its category changes at each stage: what the application supplies, what the platform derives, what it decides, what a person adds, and what is kept.
| Stage | Category | Data |
|---|---|---|
| AI output and context | Input | The generated response or proposed action, with its original context and the source’s API credential |
| Source and policy selection | Processing | The credential resolved to an AI source, and the policy and version assigned to it |
| Validation checks | Processing | Enabled checks evaluate the output independently |
| Evidence | Audit data | Per-check results, confidence information and evaluation evidence |
| Final decision | Decision | The most severe ruling: Pass, Flag or Block |
| Application | Output | The structured response, on which the application branches |
| Reviewer, if required | Human intervention | Inspection of evidence and check results, and a decision tied to the reviewer |
| Audit record | Audit data | Ruling, evidence, policy and version, reviewer information, decision history |
Input is the only part the application controls, and the decision is the only part it consumes. Evidence and history stay in the platform for reviewers and investigators.
Technical Challenges Solved
Each engineering problem raised at the start maps to a specific part of the design.
| Challenge | How the architecture addresses it |
|---|---|
| Unreliable output | Hallucination and Contradiction Detection compare output with supplied context, and unverifiable results go to review |
| Rule and privacy enforcement | Policy Violation Detection applies configurable thresholds per source, and PII Leak Detection acts as a privacy layer before delivery |
| Unsafe automated actions and workflows | High-Risk Action Detection routes risky outputs for review, and Routing Validation checks workflow decisions before downstream processing |
| Code and brand quality | Code Convention Validation checks generated code against configured conventions, and Tone and Brand Safety evaluates content, with tone trends in analytics |
| Multi-application governance | Per-source credentials, policies, thresholds and case tracking |
| Human review | Flagged and blocked cases enter a reviewer workflow on web and mobile |
| Auditability | Rulings, check results, evidence, policy version, reviewer and history are retained |
| Webhook reliability | Queue workers, retries and backoff, with signed requests |
| Role separation | A reviewer role with no administrative configuration access |
Final Architecture Summary
Taken together, the system works as a centralized AI safety gateway that sits between AI models and the people or business actions their output could reach.
Figure 4. The overall structure: AI Agent → Safety Validation → Pass / Flag / Block → Human Review if Required → Customer or Business Action → Audit Trail.
That structure provides seven properties:
- Controlled output delivery. Nothing reaches a customer or triggers an action on the strength of generation alone.
- Configurable validation. Eight checks can be enabled and thresholded independently.
- Application-specific policies. Each AI source is judged by its own versioned rules.
- Human oversight. Flagged and blocked cases have a defined route to a reviewer on web or mobile.
- Traceability. Every case can retain its ruling, evidence, policy version and reviewer activity.
- API-based integration. Connected applications submit output and context and branch on a structured ruling.
- Multi-application support. One installation governs several AI products without merging their rules.
The central design choice is the severity rule: the most severe ruling wins, and anything that cannot be verified or completed is routed to a person instead of passed. The rest of the architecture exists to make that rule configurable, observable and accountable.
Want output validation and human review built into your own AI application?
Zipprr can walk you through how a guardrail layer would fit your stack, with no obligation. Schedule a free demo or email us at [email protected].
Final Architecture Summary
Taken together, the system works as a centralized AI safety gateway that sits between AI models and the people or business actions their output could reach.
AI Agent → Safety Validation → Pass / Flag / Block → Human Review if Required → Customer or Business Action → Audit Trail
That structure provides seven properties:
- Controlled output delivery. Nothing reaches a customer or triggers an action on the strength of generation alone.
- Configurable validation. Eight checks can be enabled and thresholded independently.
- Application-specific policies. Each AI source is judged by its own versioned rules.
- Human oversight. Flagged and blocked cases have a defined route to a reviewer on web or mobile.
- Traceability. Every case can retain its ruling, evidence, policy version and reviewer activity.
- API-based integration. Connected applications submit output and context and branch on a structured ruling.
- Multi-application support. One installation governs several AI products without merging their rules.
The central design choice is the severity rule: the most severe ruling wins, and anything that cannot be verified or completed is routed to a person instead of passed. The rest of the architecture exists to make that rule configurable, observable and accountable.
Related Zipprr resources
Zipprr’s products are independently developed, and this case study does not describe any of them as integrated with the platform. These pages cover related AI applications and technical write-ups.
- AI Chat: a self-hosted, white-label AI chat assistant, the kind of AI application whose output a guardrail layer would validate.
- AI Lawyer: AI-assisted legal document drafting and contract review, another field where AI output needs a human decision.
- WhatsApp Automation: messaging automation with AI-assisted responses.
- Multi-Sector Booking and Reservation App: A Technical Architecture Case Study: another architecture-first write-up in the same series.
- AI-Powered WhatsApp CRM and Marketing Automation SaaS: a case study on messaging, AI agents and automation.
- Zipprr product catalog and more Zipprr case studies.
