Domain service reference
GEO Platform separates domain decisions so observation, analysis, generation, external execution and learning can scale and fail independently. The control plane authorizes and orchestrates requests; each service owns its domain contract.
Common runtime contract
| Endpoint | Meaning |
|---|---|
GET /healthz | Process is alive |
GET /readyz | Required configuration is usable and the instance may receive work |
GET /v1/capabilities | Service name, version and supported domain operations |
| Domain endpoint | Validated operation request and domain-specific result |
All internal calls require a scoped service identity. Domain requests carry workspace and operation context; a service never expands access based on a resource UUID alone.
Capability topology
Core and component services
geo-core-service
Owns Target Graph validation, canonical identity, typed relations, merges, versioning and cycle protection.
| Contract area | Detail |
|---|---|
| Inputs | Targets, aliases, relations, validity windows, ownership and policy metadata |
| Outputs | Validated graph mutation, canonical merge, graph version, applicability or validation error |
| Dependencies | Workspace authorization context and canonical persistence |
| Failure behavior | Rejects cycles, cross-workspace references and invalid relation semantics without partial graph mutation |
| Key signals | Validation failures, merge conflicts, cycle attempts and graph-version age |
geo-component-service
Owns the AI-system graph: providers, engines, models, custom agents, MCP servers/tools, RAG sources, routers and workflows.
| Contract area | Detail |
|---|---|
| Inputs | Component type, version, capabilities, configuration and dependency edges |
| Outputs | Capability resolution, dependency validation and evaluation context |
| Failure behavior | Rejects missing/cyclic dependencies and unsupported capability requests |
| Key signals | Disabled dependencies, version drift and evaluation failures |
Observation and intelligence services
geo-observation-service
Executes approved run manifests against configured providers and stores immutable answer evidence.
| Contract area | Detail |
|---|---|
| Inputs | Prompt, provider/component version, market, language, target scope, repetition and evidence policy |
| Outputs | Answer, citations, normalized input/output/cached/reasoning tokens, provider-reported web searches and cost, latency, status and provenance |
| Failure behavior | Bounded retry by failure class; completed snapshots are not overwritten; partial runs remain visible |
| Key signals | Provider error/rate-limit rate, freshness, latency, token/search usage, configured/provider-reported/unpriced cost coverage and incomplete runs |
geo-intelligence-service
Applies versioned metric definitions to eligible evidence and produces metric snapshots, gaps and findings.
| Inputs | Observation set, metric definition, target/component applicability and dimensions | | Outputs | Numerator, denominator, value, unit, sample size, confidence, low-sample state and evidence links | | Failure behavior | Leaves observations intact; failed calculations can be retried under the same definition version | | Key signals | Low-sample frequency, calculation errors, metric-version drift and stale datasets |
geo-entity-service
Resolves mentions to canonical Target Graph entities.
| Inputs | Mention text, context, aliases, candidate targets, market and language | | Outputs | Resolved target and confidence, or ambiguous/unresolved state with candidates | | Failure behavior | Does not force a match below confidence policy | | Key signals | Ambiguous and unresolved mention rates, alias coverage and manual-review age |
geo-citation-graph-service
Builds relationships among answers, citations, source domains, claims and targets.
| Inputs | Answer/citation evidence and target/claim links | | Outputs | Versioned nodes, edges, coverage, source influence and gaps | | Failure behavior | Preserves invalid/unreachable citation status as evidence instead of silently dropping it | | Key signals | Citation extraction success, broken source rate and graph freshness |
geo-prompt-demand-service
Clusters prompts, identifies intent and compares demand with measurement/content coverage.
| Inputs | Prompt corpus, topic, market, language, intent and optional demand signals | | Outputs | Clusters, coverage, unmet demand and recommended prompt-set changes | | Failure behavior | Keeps cluster version and does not rewrite earlier reporting dimensions | | Key signals | Unclustered prompts, uncovered clusters and cluster-version changes |
geo-narrative-service
Analyzes claims, sentiment, themes, factual consistency, unsupported statements and brand-safety risk.
| Inputs | Answer/content corpus, canonical targets and approved knowledge | | Outputs | Narrative themes, claim assessments, sentiment and safety findings with evidence | | Failure behavior | Flags insufficient evidence; never treats model classification as an authoritative fact | | Key signals | Unsupported-claim rate, high-risk findings and review backlog |
Knowledge, content, and activation services
geo-brand-knowledge-service
Owns approved facts, claims, validity windows, source evidence and answer-to-knowledge assessment.
| Inputs | Knowledge entries, sources, answers and policy | | Outputs | Supported, missing, conflicting, expired or unverified claim results | | Failure behavior | Excludes expired/unapproved facts from generation grounding | | Key signals | Stale entries, source availability and claim-conflict rate |
geo-content-service
Creates evidence-grounded briefs and assets while retaining source lineage and versions.
| Inputs | Recommendation, target, approved knowledge, channel, format, goal and provider | | Outputs | Draft version, source entries, proposed metadata and review state | | Failure behavior | Fails closed when required facts lack approved evidence; generated output never auto-approves itself | | Key signals | Generation failure, ungrounded-claim review, revision count and approval lead time |
geo-channel-service
Owns destination adapter contracts for preview, publish, verify and rollback.
| Inputs | Approved content version, channel connection, destination, schedule and idempotency key | | Outputs | Preview/diff, attempt, external reference, verification and rollback result | | Failure behavior | Retries safe failures, records dead-letter state and never labels an unverified operation complete | | Key signals | Publish/verify latency, retry count, dead letters and rollback rate |
geo-action-service
Owns proposed operational changes, risk, approval, policy, dry run, execution, verification and rollback.
| Inputs | Recommendation, proposed diff, owner, risk, dependencies, approval and idempotency | | Outputs | Action state, attempts, execution result, verification and rollback | | Failure behavior | Blocks missing approval/policy and deduplicates repeated execution requests | | Key signals | Approval age, failed actions, verification failures and rollback readiness |
Measurement and learning services
geo-tracking-service
Accepts consent-aware behavioral and crawler events through a site-scoped token.
| Inputs | Event, timestamp, page, referrer, campaign/publication context, consent and pseudonymous IDs | | Outputs | Accepted/deduplicated status, sanitized event and coverage signals | | Failure behavior | Rejects invalid origin/token/event; drops or limits data according to consent and retention policy | | Key signals | Acceptance, deduplication, origin rejection, consent drop and retention cleanup |
geo-attribution-service
Allocates outcomes to eligible publication, action and campaign touchpoints.
| Inputs | Touchpoints, outcomes, window, model and tracking coverage | | Outputs | First/last/linear/position-based allocation and confidence | | Failure behavior | Leaves outcomes unattributed when evidence is insufficient; does not force a match | | Key signals | Coverage, unattributed rate, model variance and confidence distribution |
geo-experiment-service
Owns experiment design, assignment context, sample plan, stop rules and observed result evaluation.
| Inputs | Hypothesis, control/candidate, metric, sample plan, guardrails and observations | | Outputs | Variant values, confidence, winner/no-winner and stop/cancel state | | Failure behavior | Preserves collected data after stop/cancel and marks invalid designs explicitly | | Key signals | Sample progress, guardrail breach, duration and inconclusive rate |
geo-simulation-service
Produces synthetic estimates for organic, ads, sponsored-agent, custom-agent, MCP/RAG and workflow scenarios.
| Inputs | Baseline, profile/component version, assumptions, parameters and scenario | | Outputs | Expected change, prediction interval, confidence, cost and latency assumptions | | Failure behavior | Labels all outputs synthetic and never writes observation tables | | Key signals | Calibration error, profile drift and out-of-range assumptions |
geo-autopilot-service
Creates goal-constrained plans with dependency order, budgets and approval checkpoints.
| Inputs | Goal, target scope, budget, policy, available actions and current evidence |
| Outputs | Explainable plan, dependencies, projected cost and executable state |
| Failure behavior | Defaults to executable=false; stops on policy, budget, dependency or emergency-stop failure |
| Key signals | Plans awaiting approval, blocked dependencies, budget stops and emergency stops |
Reporting service
geo-reporting-service
Generates immutable reports and exports from authorized versioned datasets.
| Inputs | Dataset, filters, columns, comparison, layout, format, schedule and delivery connection | | Outputs | JSON, CSV, NDJSON, XLSX or PDF artifact; delivery attempts and share metadata | | Failure behavior | Keeps a generated report when delivery fails; share links remain expiring and revocable | | Key signals | Generation duration, delivery failure, artifact expiry and share access |
Cross-service invariants
- Organization, Tenant, and Workspace context is mandatory.
- Raw observations, executions and verifications are immutable.
- Synthetic results never enter observed metric denominators.
- External mutations require a connection, capability, policy and approval.
- Idempotency applies to graph mutation, action execution, publication and external delivery.
- Credentials are resolved server-side and never returned in capability responses.
- Every derived result links to definition version and source evidence.
- Failure is visible and retryable; no service converts unknown state into success.