← Back to directory

analytics-and-evolution.md

architecture/analytics-and-evolution.md · 14.8 KB · 2026-11-02 12:48

Analytics and Evolution

Status: settled semantic contract, 2026-09-11; broader analytics/evolution implementation follows the first bounded milestone. Owner: Analytics and Evolution/Optimisation reusable execution responsibilities and the closed improvement loop. Examples establish conceptual expectations, not fixed metrics, thresholds, autonomous-change tiers, or a release promise.

Canonical Prerequisites

Scope and Shared Model

Analytics makes business and platform operation measurable; Evolution/Optimisation turns evidence into inspectable candidate improvements. Neither responsibility is limited to marketing, and neither inherently requires AI. Measurements, metric definitions, reports, observations, proposals, goals, decisions, and outcomes use the universal model when persistent/addressable. Their type definitions and configurations are themselves addressable; they do not form a separate analytics or AI-memory universe. Relationships connect evidence to business subjects, workflow executions, relevant goals, decisions, and implemented changes. Aggregated or cached results are derived from the shared model and identified external sources, not replacement foundations. An engine is a reusable execution responsibility, not a mandated service, analytics warehouse, or class. Product priorities and demonstrator depth belong to Roadmap, not the full responsibility list here.

Analytics, network observations and learning-like pattern recognition remain higher-level interpretations over Data, Workflow, Logic and their relationships; none is an additional semantic role or authoritative network primitive. Marketing measures and recurring Marketing structures may provide derived evidence for a candidate pattern, but the path remains Observe -> Understand -> Suggest -> Approve -> Implement -> Measure. A Business-specific configuration can inform a reusable platform pattern only after explicit human authority; Analytics or Evolution must not automatically promote or mutate a platform Definition.

Analytics Responsibility

Inputs include authorised business state, historical observations, workflow/action outcomes, and source-attributed external measurements. Actions include measurement definition, collection coordination, aggregation, comparison, trend analysis, and report preparation. Outputs include explainable metrics, reports, dashboard projections, and evidence usable by people and the improvement loop. Each result needs meaningful subject, metric definition, time basis, scope, source, and material completeness limitations. Measurement should relate actual outcomes to relevant goals rather than assuming any rising number means success. Deterministic counters, durations, completion rates, and rules can supply useful analytics without a model provider. External collection is an Integration responsibility and scheduled collection/report delivery uses Workflow and Automation/Scheduling. Analytics consumes the results; it does not silently create its own connector, scheduler, or permission model. Unavailable inputs, delayed observations, inconsistent metric definitions, and denied access must be visible rather than converted into false zeroes.

Operational activity is business information as well as technical telemetry. Where useful and authorized, measurements may summarize automated Logic operations, Workflow triggers and actions, human approvals and rejections, external operations, imported datasets, significant configuration changes and other consequential activity. Each summary must retain its subject, source, scope, time basis, definition and material limitations; counts do not replace the underlying history or prove that an external Effect succeeded.

Measurement and Historical Evidence

Keep historical measurements identifiable so trends and before/after comparisons do not rely only on overwritten current totals. Canonical Time and Events determines correction, retention, reconstruction, and recorded/effective-time behaviour; no event-sourcing mechanism is prescribed here. For imported metrics, distinguish the period measured, the source's observation date when known, and when the platform collected the result. Preserve metric meaning, units, aggregation scope, and relevant denominator so apparently similar numbers are not conflated. For example, a conversion rate and conversion count need different interpretation, and channels may define engagement differently. Source authority and measurement confidence are distinct: a calculated estimate must not be presented as an external system's confirmed total. An absent measurement is not evidence of no activity; late data can change an earlier comparison and must be explainable. Historical comparisons must disclose material changes in metric meaning or subject selection. Access applies to source records, derived aggregates, exports, and explanations, including counts that could reveal restricted activity. Exact aggregation windows, attribution models, refresh intervals, and correction rules remain explicit decisions rather than universal defaults.

Reporting and Operational Views

Support time series, comparisons, key measures, and meaningful filters for business subjects and date ranges. Operational examples include workflow duration, repeated manual work, exception rates, neglected customers, and missing information. Marketing examples retain impressions, clicks, engagement, conversions, follower growth, and per-content/campaign/channel aggregation. Top-performing content and channel comparisons are useful projections, not the platform's only reporting vocabulary. Line charts, bar charts, and KPI presentations should expose metric context and missing data rather than decorate an empty result. Scheduled reports, business-facing dashboards and PDF/CSV export remain broader capability requirements, not first-milestone deliverables. Views and content owns projections; UI system owns visual/interaction conventions. Predictive analytics and anomaly detection are optional expansion areas, not prerequisites for trustworthy reporting. The older Analytics application source describes a placeholder; that is not evidence of metric collection, charts, exports, or a new Analytics Engine.

Evolution/Optimisation Responsibility

Inputs include authorised observations, goals, constraints, process context, measurements, exceptions, and accumulated knowledge. The responsibility identifies and evaluates potential improvements, exposes proposals, and measures approved changes. Observe workflow performance, user behaviour, repeated actions, exceptions, data quality, unused features, customer behaviour, marketing performance, and operational metrics. Candidate improvements include repetitive work, inefficient workflows, duplicate processes, missing automation, and unusual performance. Also consider neglected customers, missing information, emerging business activities, formalising knowledge, new structured properties, workflows, and views. Outputs include evidence-linked proposals and evaluation outcomes, not silently applied changes or fabricated causal certainty. Significant changes should normally be proposed for review; any permitted automatic action remains governed by explicit policy. A deterministic rule or a human analyst can recognise a pattern; AI can assist but does not own the loop.

Improvement Loop

The complete loop is Observe -> Understand -> Suggest -> Approve -> Implement -> Measure. Skipping review or outcome measurement is not the intended self-evolution contract.

Observe

Capture a repeated action, exception, performance change, or other relevant signal with source, subject, and time context. Distinguish observed behaviour from inference about its cause; absence of a signal is not evidence that a process is working well.

Understand

Relate observations to business context, existing workflows, applicable knowledge, goals, and constraints. Assess whether the pattern is meaningful, including data quality, permissions, thresholds, and plausible alternative explanations. Threshold values are explicit governed business configuration, not locally invented autonomy levels. Missing configuration cannot authorise automatic change.

Suggest

Present a readable candidate change, supporting evidence, affected objects/configuration, intended outcome, and material uncertainty. A proposal may change a view, property, workflow, or knowledge structure; configuration is preferred where existing responsibilities suffice. A recommendation is not an approved Decision or an executable command merely because it is well written.

Approve

Use the authoritative approval contract in Identity and Governance for reviewer authority, applicable policy, and the decision. Reviewers can approve or reject; the decision and rationale should remain linked to the proposal and evidence. This stage does not define fixed risk tiers, delegation rules, or approval invalidation behaviour.

Implement

Apply a permitted, valid change through the relevant platform action/workflow responsibility after required approval. Validate affected types, relationships, permissions, and policy; approval does not make invalid configuration executable. Record what was actually changed and any failure or partial result, rather than assuming acceptance means completion.

Measure

Compare relevant outcomes against the stated objective and baseline, with time/context limitations visible. Retain both beneficial and disappointing results; an approved proposal is not automatically a successful improvement. Feed the outcome and explanation into institutional knowledge/history for later decisions and further observation.

Three Post-Sale Tasks Example

Observation: users manually create the same three tasks after every sale. Suggestion: configure an automated post-sale workflow using existing task, relationship, workflow, and communication capabilities. Approval: an authorised manager reviews the proposal, its evidence, affected work, and intended improvement. Implementation: the approved valid workflow is made available/active through governed platform actions, not arbitrary AI code changes. Measurement: compare process duration before and after, taking account of volume or process changes that affect interpretation. The source's detailed progression is retained:

1. The system observes repeated manual actions. 2. Evolution detects a pattern, using deterministic or optional AI-assisted analysis. 3. The pattern is assessed against permissions and applicable thresholds. 4. Idiosyncrasy proposes an optimisation. 5. A user reviews the proposed change and supporting context. 6. The authorised user approves or rejects it under governance. 7. If approved and valid, configuration is updated through the platform execution boundary. 8. The system measures the result rather than treating activation as proof of success. 9. The outcome becomes part of business knowledge/history, linked to the proposal, decision, and implementation.

Positive and Negative Examples

Positive: a deterministic count highlights repeated task creation, a person assesses the cause, and a reviewed workflow change is measured. Positive: repeated customer-contact observations produce a proposed structured preference while preserving the original explanation in Knowledge. Positive: a report marks delayed external metrics and declines to compare incompatible engagement definitions as though identical. Negative: an AI confidence score automatically authorises a workflow change or establishes a claim of business benefit. Negative: overwriting all prior measurements with today's totals removes the evidence needed to explain a change. Negative: collecting only marketing KPIs excludes operational work and defeats the business-wide evolution responsibility. Negative: storing rejected suggestions only in provider chat discards institutional decision history and no-AI access.

Implementation and Acceptance

The settled contracts govern observations, historical evidence, proposals and effects. Initial measurement can query durable transition/outcome records for counts and durations; retain definition, Business scope, time basis and missing-data qualifications. A suggestion is a typed proposal linked to that evidence; review and any resulting configuration mutation use the shared Command path. These are mechanisms for later bounded observation, not an autonomous optimisation subsystem or a prerequisite to the first login/mutation milestone.

Acceptance checks: measure non-marketing work without AI; explain source/time/scope; distinguish missing data from zero; demonstrate all six loop stages; record approval and actual effects separately; retain outcome-linked institutional history. Implementation architecture, Development, and Implementation status own mechanisms, checks, and evidence.

Source Lineage

Source map and documentation ownership own traceability. 01 product and principles, self-optimisation and growing knowledge; 02 technical architecture, Evolution Engine and three-task example; 03 engines and MVP, analytics priority and nine-step optimisation case; 00 combined handoff, corresponding sections provide the foundation. Older analytics feature/UI/application documents and metrics-table notes contribute reporting, snapshots, missing/delayed data, comparisons, export, and placeholder evidence, not their physical schemas or a marketing-only scope.