Global KYC/KYB Guide

Global KYC/KYB should not be implemented as one global database. It should be implemented as regional TeaQL models behind unified service contracts, with every data access passing through an auditable runtime boundary.

This guide describes an architecture pattern for cross-country KYC and KYB applications where countries or regions can keep local data models, local databases, local compliance rules, and local user experiences while still exposing a consistent verification service to the global application.

Core Pattern

Use a regional implementation model:

Global Application
  -> Unified KYC/KYB Service Contract
  -> Regional TeaQL Runtime
  -> Regional TeaQL Model
  -> Regional Database / Evidence Store

The global application should call a service interface. It should not receive direct database connections, table access, or raw SQL capability.

Regional Model, Unified Service Contract

KYC and KYB requirements vary by country and region. A single global model usually becomes either too weak for strict jurisdictions or too complicated for simple ones.

Each region can run its own TeaQL model for local requirements:

• Individual identity document types
• Company registration numbers
• Beneficial owner structures
• Local address formats
• Tax identifiers
• Consent records
• Evidence retention rules
• Manual review workflows
• Regulator-specific decision records

The global application can still use a unified service contract:

verifyPerson(...)
verifyBusiness(...)
getVerificationStatus(...)
requestAdditionalDocuments(...)
recordManualReview(...)
auditVerificationDecision(...)

The contract gives global systems a stable integration point while allowing each region to keep its local data shape and compliance policy.

Do Not Expose Direct Database Access

For compliance-sensitive KYC/KYB systems, direct database access is the wrong boundary.

External systems or cross-region callers should not receive:

• Database credentials
• Table-level access
• Raw SQL access
• Replicated evidence tables
• Uncontrolled exports of identity documents or business registration evidence

All access should go through TeaQL services and runtime execution. This matters because the TeaQL runtime can record and enforce the access path:

• Who accessed the data
• Which tenant, user, or system actor initiated the request
• Why the data was accessed
• Which service operation was used
• Which entities or fields were touched
• Which jurisdiction handled the request
• Which audit metadata and runtime policy applied

This audit boundary is more important than a shared database schema. It lets teams reason about data access as controlled business operations instead of uncontrolled storage access.

Local Runtime as the Compliance Boundary

A regional TeaQL runtime can be deployed inside the relevant country or regulatory region. That runtime connects to the local database, applies the local model, and enforces local policies.

The global application calls the regional service, but the original evidence can remain local:

Global App
  -> KYC/KYB service call
  -> EU TeaQL runtime
  -> EU model and EU database

Global App
  -> KYC/KYB service call
  -> Singapore TeaQL runtime
  -> Singapore model and Singapore database

This pattern helps reduce cross-border data transfer risk because the global application does not need to pull raw identity documents, registration certificates, beneficial-owner files, or audit evidence into a central database.

Unified Status, Local Evidence

Most upstream systems do not need full KYC/KYB evidence. They usually need a normalized status and a small set of decision metadata.

For example:

Status	Meaning
pending	Verification has started but is not complete.
verified	The person or business passed the configured regional checks.
rejected	Verification failed.
expired	Existing verification is no longer valid.
requires_more_documents	The regional flow needs additional evidence.
manual_review	A reviewer must make or approve the decision.

Raw evidence can stay inside the regional system. The service can return only what the global application needs:

• Verification status
• Decision timestamp
• Expiration timestamp
• Review reason code
• Required next action
• Region or policy version
• Audit reference ID

This keeps the global system useful without turning it into a global repository of sensitive identity and company evidence.

Regional Frontend Experience

The KYC/KYB frontend should not assume every country has the same form.

Different regions may require different:

• Identity document types
• Address fields
• Company registration fields
• Beneficial owner fields
• Privacy notices
• Consent text
• Language and date formats
• Required file uploads
• Manual review instructions

There are two practical frontend patterns.

Local Frontend Deployment

Each country or region can host its own KYC/KYB frontend. The global application redirects the user to the local experience and receives a result or callback when verification completes.

This works well when the local team must fully control consent text, data collection, hosting region, analytics, and evidence upload behavior.

Service-Driven Regional Forms

The regional TeaQL service can return a form schema, page definition, or server-driven UI payload. The global application renders the correct local flow without hard-coding every regional variation.

This works well when the product wants a unified shell but still needs local fields, local validation, local privacy text, and local next actions.

What TeaQL Adds

TeaQL is useful in this architecture because it provides a controlled layer between global applications and local compliance data:

• Model-driven local data shape: each region can model the fields and relationships it actually needs.
• Generated typed APIs: service code uses generated business APIs instead of raw SQL or ad hoc table access.
• Runtime-level audit trail: access flows through a runtime boundary where identity, purpose, comments, audit metadata, and policy can be captured.
• Jurisdiction-specific policy enforcement: local runtime logic can apply regional tenancy, retention, masking, and authorization rules.
• Unified contract across different models: global systems call stable KYC/KYB operations even when regional models differ.
• Reviewable implementation: reviewers inspect generated API usage and service contracts instead of reconstructing database access from scattered SQL.

Recommended Architecture Rules

Use these rules when designing global KYC/KYB with TeaQL:

1. Keep raw evidence in the jurisdiction where it belongs unless there is a reviewed legal basis for transfer.
2. Expose service operations, not database connections.
3. Return normalized status and decision metadata to global systems.
4. Keep region-specific fields in regional models.
5. Route every data access through TeaQL runtime context and audit metadata.
6. Treat frontend forms as regional experiences, either locally hosted or service-driven.
7. Keep compliance review focused on service contracts, runtime policy, audit output, and cross-border data movement.

Review Checklist

Before approving a global KYC/KYB implementation, review:

• Which jurisdiction owns each model and database.
• Whether global systems can access raw evidence.
• Which service contract is exposed to global callers.
• What audit metadata is recorded for each verification operation.
• Whether the frontend form is local, service-driven, or global.
• Which fields are returned across borders.
• How status, rejection reason, expiry, and manual review are normalized.
• How consent, privacy notice, retention, and deletion behavior differ by region.