Architecture and service topology

This document describes how GEO Platform is divided, which component owns each decision, and how observed evidence moves from an AI provider or tracking source into metrics, actions, publications, and verified outcomes.

System context

GEO Platform is the operating layer between brand teams, AI systems, owned channels, analytics sources, and downstream work-management tools. It does not replace a CMS, analytics warehouse, model provider, or customer identity platform. It coordinates them through workspace-scoped contracts.

Plane responsibilities

Plane	Owns	Must not own
Control plane	Authentication, tenant and workspace access, configuration, approval, policy, audit, public API and dashboard orchestration	Provider credentials in browser state; domain metric calculation
Observation plane	Prompt execution, provider adapters, immutable answer snapshots, citations, request cost and latency	Share-of-voice interpretation; publishing
Intelligence plane	Metric contracts, entity resolution, citation graph, prompt demand, narrative, accuracy and safety signals	Rewriting raw observations; external mutations
Optimization plane	Findings, recommendations, priority, expected lift, ownership and verification plans	Executing an unapproved change
Activation plane	Knowledge, content versions, channel adapters, preview, publication, verification and rollback	Treating a preview as published
Performance plane	AI referral collection, outcomes, touchpoints, attribution and experiment results	Claiming causality without experimental evidence

Control plane and domain services

The authenticated web application is the Backend for Frontend (BFF) and control plane. It verifies Organization, Tenant, Workspace, role and capability before it asks a domain service to work. Domain services own calculations and execution contracts; the BFF must not duplicate their business logic.

Service catalog

Every runtime exposes GET /healthz, GET /readyz, GET /v1/capabilities, and a domain endpoint. Health only proves that the process is alive. Readiness proves that required configuration is usable. Capabilities declare the contract the control plane may route to that instance.

Runtime	Domain responsibility	Representative input	Representative output
geo-core-service	Target Graph validation, canonical identity and graph operations	Targets, relations, aliases, graph version	Validated graph result, merge or cycle error
geo-component-service	AI component registry and dependency evaluation	Provider/model/agent/MCP/RAG/workflow component	Component capability and dependency result
geo-observation-service	Provider-backed prompt execution	Prompt, market, language, provider, repetition	Immutable answer/evidence snapshot
geo-intelligence-service	Versioned metrics and gap calculation	Observation set and metric contract	Metric snapshots and findings
geo-brand-knowledge-service	Approved fact and claim assessment	Answer, facts, validity and source evidence	Supported, missing or conflicting claim result
geo-content-service	Evidence-grounded brief and asset generation	Recommendation, approved knowledge, channel goal	Versioned draft and provenance
geo-channel-service	Preview, publish, verify and rollback adapters	Approved content, connection and destination	Publication attempt and verification result
geo-simulation-service	Synthetic scenario estimation	Baseline, assumptions, component and parameters	Prediction interval, expected change and cost
geo-action-service	Action policy and execution contract	Proposed diff, approval, risk and idempotency	Execution, verification or rollback state
geo-reporting-service	Report/export generation	Dataset, filters, layout and format	Immutable report or export artifact
geo-tracking-service	Consent-aware event ingestion and maintenance	Site token, event, pseudonymous identifiers	Accepted/deduplicated event and coverage
geo-attribution-service	Touchpoint-to-outcome allocation	Publications, actions, campaigns and events	Model-specific attribution result and confidence
geo-entity-service	Canonical entity and alias resolution	Mention and candidate targets	Resolved, ambiguous or unresolved entity
geo-citation-graph-service	Citation-source relationship analysis	Answers, citations, source and target links	Nodes, edges, influence and coverage
geo-prompt-demand-service	Prompt clustering and demand gaps	Prompts, intents, observed topics	Clusters, demand and coverage gaps
geo-narrative-service	Claim, theme, sentiment and safety analysis	Answer/content corpus and knowledge	Narrative, factual consistency and risk result
geo-experiment-service	Experiment assignment and result evaluation	Design, variants, metric and samples	Observed values, confidence and winner
geo-autopilot-service	Goal-constrained planning	Goal, budget, dependencies and policy	Non-executable or approval-bound plan

Observation request sequence

Asynchronous worker topology

Long-running and external work is claimed by workers. A worker receives a scoped internal identity, leases bounded work, calls the owning domain service, records the result, and releases or reschedules the item. A timeout must not create a second publication or action.

Evidence and state classes

Class	Example	Mutability rule	Can affect observed metrics?
Configuration	Provider, prompt set, schedule, dashboard definition	Versioned updates	Indirectly, for future runs
Observed	Provider answer, citation, tracking event	Append-only snapshot	Yes
Derived	Metric, entity resolution, narrative, finding	Recomputed into a new version	Yes, with declared contract version
Synthetic	Simulation result	Immutable scenario result	No
Planned	Recommendation, draft, proposed action	Workflow transitions and versioned edits	No
Executed	Publication/action attempt	Append-only attempts and results	Only after verification and later observation
Verified	Post-action check, experiment result	Immutable verification record	Yes, as evidence rather than rewritten history

Failure isolation

• A provider outage degrades only runs using that provider; existing evidence and other providers remain queryable.
• An intelligence-service failure leaves observations intact and retryable; it does not rerun the provider request automatically.
• A publishing failure creates a failed attempt and retry/dead-letter record; it does not mark content as published.
• Tracking ingestion remains isolated from dashboard reads and publication execution.
• Report-delivery failure does not delete the generated immutable report.
• Autopilot failure cannot bypass action policy, approval, idempotency or emergency stop.

Deployment patterns

Shared control plane with independent services

Recommended for production. One authenticated control plane routes work to independently scalable services through internal service discovery.

Consolidated development runtime

Local development may run the same capability contracts from a shared runtime image with a service-name configuration. This reduces local operational overhead but does not change ownership: each configured instance advertises one domain capability and must be tested through its own health, readiness, capability and execution endpoints.

Observability requirements

Correlate every request with Organization, Tenant, Workspace, operation, run/action/publication identifier and trace ID. Logs must redact credentials and sensitive prompt/evidence content according to policy.

Minimum service signals:

• Request rate, duration, status and retry count
• Provider request count, token usage, cost and rate-limit state
• Queue age, lease contention and dead-letter growth
• Observation freshness and incomplete-run count
• Publication/action verification failure rate
• Tracking acceptance, deduplication and consent-drop rates
• Metric version, sample size and low-confidence frequency

Related documentation

• Tenants, workspaces, projects, and targets
• Data model and lifecycle
• Integration selection guide
• Deployment and configuration
• Security, privacy, and governance