Data model and lifecycle
GEO data is organized around a workspace-scoped graph and an immutable evidence lineage. Configuration can evolve, but a historical result always retains the target, prompt, provider, metric contract and evidence versions that produced it.
Tenant and portfolio model
| Resource | Purpose | Isolation boundary |
|---|---|---|
| Organization | Shared customer identity and product access | Membership and licensed-product policy |
| Tenant | GEO product boundary, team, billing, API keys and tenant-level operations | No cross-tenant Workspace access |
| Child Tenant | Optional regional or operational boundary below a root Tenant | One level only; owns isolated Workspaces |
| Workspace | Operational data, providers, connections, projects and dashboards | Primary configuration and data boundary |
| Project | Business objective, markets, languages, target portfolio and measurement program | Reporting and ownership boundary inside a workspace |
| Target | Canonical object being measured or changed | Reusable across projects in its workspace |
Target Graph
The graph represents the real relationship between a brand and the objects that influence how AI systems understand it.
Supported target types include organization, brand, merchant, website, page, content, product line, product, service, campaign, message, claim, person, topic, market, audience and channel asset.
Target fields
| Field group | Examples | Rule |
|---|---|---|
| Identity | Canonical name, external ID, canonical URL | Stable inside the workspace |
| Classification | Owned, competitor, contextual | Required before competitive interpretation |
| Localization | Markets, languages, localized names | Preserve market/language applicability |
| Discovery | Aliases, domains, source references | Do not create duplicates for spelling variants |
| Governance | Owner, access policy, status | Required for action assignment and visibility |
| Versioning | Version, valid-from, valid-to, replaced-by | Historical evidence keeps its original version |
| Metadata | Type-specific JSON | Must not replace canonical typed fields |
Relation contract
A relation declares source, destination, type, weight, validity window and provenance. Examples include owns, part_of, represents, published_on, targets, supports, contradicts, competes_with and related_to.
Cycle rules depend on relation semantics. Hierarchical ownership must remain acyclic. Contextual relations may be bidirectional but must not be used to create a false ownership roll-up.
Research and observation model
| Resource | Mutable? | Notes |
|---|---|---|
| Topic | Yes, with audit | Business question or discovery domain |
| Prompt | Yes, with version context | Market/language-aware input with intent and tags |
| Prompt set | Yes, with membership history | Repeatable measurement unit |
| Run manifest | No | Freezes prompts, providers, targets, repetitions and budgets |
| Answer snapshot | No | Provider output and normalized evidence |
| Metric snapshot | No | Calculation result tied to a metric definition version |
Replaying a run creates a new manifest and new snapshots. It never replaces an answer because provider behavior, source availability and model versions can change.
Workspace usage ledger
The usage ledger is separate from answer evidence. It records one direct provider-call event with Organization, Tenant, Workspace, provider, operation, status, model, request count, normalized token dimensions, web-search requests, cost components, currency, pricing source, latency and optional related run/action identity.
This separation allows Explore, Action Plan generation and provider tests to be metered even when they do not create a monitoring answer snapshot. The provider reference may become null after provider deletion, but the historical event and its provider metadata remain. Cross-workspace provider references fail the database scope check.
Metric lineage
A metric snapshot must declare:
- Metric key and version
- Target and component applicability
- Numerator, denominator, operation and unit
- Sample size and low-sample threshold
- Confidence and confidence method
- Project, provider, model, market, language, topic and time dimensions
- Evidence references and calculation timestamp
Optimization and action lifecycle
Action records keep proposed diff, risk, owner, approval, policy result, idempotency key, attempts, external references, verification and rollback. Editing a recommendation does not rewrite a previously approved action.
Content and publication lifecycle
Published means the destination accepted the operation. Verified means the expected public or destination state was observed. Reports and dashboards must distinguish the two.
Tracking and attribution model
Attribution allocates observed outcomes; it does not prove causality. Experiments may provide stronger evidence when a valid control/candidate design exists.
Versioning and deletion
- Target merges preserve old identifiers and evidence references.
- Metric-definition changes create a new version and visible comparison boundary.
- Provider and component versions remain attached to their runs.
- Content edits create versions; an approved/published version is never edited in place.
- Deleting configuration prevents future use but must not corrupt historical evidence.
- Privacy deletion removes or anonymizes eligible pseudonymous tracking data while retaining non-personal aggregate integrity where policy permits.
- Audit and action execution records follow immutable retention policy.
Modeling examples
Product launch
Model the brand, product line, product, launch campaign, message, claims, product page, market and channel assets separately. This allows product visibility and campaign lift to be measured without incorrectly assigning every result to the parent brand.
Multi-market website
Use one canonical brand with localized website/page targets and market/language applicability. Use aliases for localized brand names. Do not create a separate unrelated brand solely because the domain or language differs.
Competitor benchmark
Classify each competitor explicitly, apply the same prompt set, provider, market, language and time window, and keep contextual targets out of the competitive denominator unless the metric definition includes them.