← Back to directory

02-idiosyncrasy-technical-architecture-and-data.md

archive/architecture-sources/02-idiosyncrasy-technical-architecture-and-data.md · 14.2 KB · 2026-11-02 12:48

Idiosyncrasy — Technical Architecture & Data Model

Provisional v0.2 — September 2026

1. Architectural objective

Idiosyncrasy must provide a generic, extensible runtime capable of representing different businesses without requiring a bespoke codebase for each customer.

The architecture should favour:

AI generates or modifies configuration where useful; the runtime executes the resulting configuration deterministically.

2. Core conceptual layers

Layer A — Identity and tenancy

Provides:

Layer B — Business model

Defines:

Layer C — Business data

Contains instances of the business model:

Layer D — Knowledge

Stores information that cannot or should not be forced into ordinary structured properties.

Layer E — Events and workflows

Defines what happens when business events occur.

Layer F — Presentation

Generates:

Layer G — Integrations

Connects external services.

Layer H — Intelligence

AI can reason over the preceding layers and propose or perform permitted actions.

3. Universal `id + type + value` primitive

The id + type + value primitive is the foundational data model for Idiosyncrasy. It applies to all persistent and addressable platform data, not only ordinary business records.

Conceptually:

{
    id: <unique address>,
    type: <semantic type>,
    value: <typed/configured value>
}

Examples include:

There must not be separate foundational schemas for these categories. They are all addressable instances of the same primitive.

3.1 Type provides meaning

type identifies what an object means; value contains its typed/configured content. The runtime may use type definitions to validate and interpret the value, but type definitions are themselves addressable objects using the same primitive.

A type definition may describe:

This provides schema and strong validation without making the underlying platform schema rigid.

3.2 Structured Retrieval First

The type property is a first-class structural property of every addressable object and therefore a primary indexing and retrieval dimension. The retrieval system must use it to narrow candidate objects before applying more expensive retrieval techniques.

However, type is not the only retrieval dimension. Idiosyncrasy should exploit all deterministic structure available in the Business Graph. Where useful and technically appropriate, the retrieval layer should index and use:

Retrieval should therefore progressively reduce the candidate set rather than treating the Business Graph as an undifferentiated corpus.

A conceptual retrieval pipeline is:

Query interpretation
        ↓
Type / type-family identification
        ↓
Relationship and graph constraints
        ↓
State / property / time / permission filtering
        ↓
Semantic or vector retrieval where required
        ↓
Context assembly

For example, a request such as “Which outstanding orders does Acme have from this quarter?” should first identify the relevant Customer and Order types, locate Acme's Customer object, traverse the relevant relationships, then constrain Orders by state and time. Semantic retrieval should only be introduced where it adds value.

The system should therefore not perform broad semantic or vector searches across all platform data when deterministic structure can answer or substantially narrow the query. This improves performance, predictability, relevance and cost.

Indexes are retrieval infrastructure derived from the universal object model; they are not alternative data models. A new object type must be able to participate in the retrieval system without requiring a new foundational database schema.

3.3 No special-case object model

Conceptual distinctions such as Business Graph Object, Business DNA record, Knowledge Item, Rule or Goal are semantic classifications, not competing storage primitives.

For example:

Customer      = id + type + value
Goal          = id + type + value
Decision      = id + type + value
Knowledge     = id + type + value
Workflow      = id + type + value
Relationship  = id + type + value

The Business Graph is therefore the connected set of addressable objects and relationships, rather than a separate object schema. Business DNA is the business-specific semantic/configuration model expressed through the same underlying objects.

3.3 Extensibility consequence

A new business concept does not normally require a database redesign. A new type can be introduced, its type definition created, and its relationships and behaviour configured.

A new engine is only required when genuinely new reusable execution behaviour is needed; a new data concept alone is not sufficient justification.

3.4 Scalar values remain valid

The universal primitive does not prohibit scalar values. A value inside an object may contain strings, numbers, booleans, dates, arrays or structured values where appropriate. The rule concerns the addressable unit of platform data: anything that needs identity, reuse, relationships, provenance, history or independent lifecycle should be represented as an addressable id + type + value object rather than an anonymous repeated record.

4. Addressable object principle

Business entities should be addressable objects rather than anonymous repeated values wherever identity, reuse or relationships matter.

Examples:

A property may still contain a scalar value when identity is not required.

The objective is a coherent graph of business information rather than an arbitrary collection of disconnected fields.

5. Relationships

Relationships are first-class addressable data. They follow the same id + type + value primitive when they require their own identity, metadata, lifecycle, provenance or history.

Examples:

Relationships should themselves be addressable where useful because they may eventually carry:

6. Knowledge Engine

Knowledge is a first-class platform primitive.

It exists because useful business information is not always naturally representable as a database value.

Knowledge may include:

A knowledge item should support concepts such as:

The implementation may use multiple storage/indexing mechanisms. The conceptual model must remain unified.

7. Knowledge versus structured data

Do not force every knowledge item into a property.

For example:

Structured: > Customer.preferred_contact_method = telephone

Knowledge: > "John prefers telephone because he is rarely at his desk and normally responds immediately when called."

The second may later generate a suggestion:

> "This preference has been repeatedly observed. Convert it into a structured customer property?"

The platform therefore supports an evolutionary path:

> Unstructured observation → Knowledge → Repeated pattern → Suggested structure → Structured business data

This is an important self-evolution mechanism.

8. Knowledge provenance

Knowledge must not be treated as equally authoritative.

The system should distinguish, where appropriate:

AI-generated information should not automatically become authoritative business knowledge.

The system should preserve source and confidence/provenance where practical.

9. Events

Business events should be first-class addressable objects using the same id + type + value primitive. Event payloads, provenance, timestamps and related objects are represented within the event value and/or through relationships.

Examples:

Events allow engines to remain loosely coupled.

10. Workflow model

A workflow is an addressable object using the universal primitive. Its readable configuration describes its triggers, conditions, actions, transitions and outcomes. Workflow nodes and other independently addressable components use the same primitive.

Conceptually:

> Trigger → Conditions → Actions → Outcomes

Actions may include:

Workflows should be deterministic unless an explicitly configured AI action is involved.

11. Configuration

Configuration is also platform data and must use the universal primitive where it is addressable. Configuration should be:

AI should manipulate configuration rather than directly rewriting arbitrary application code whenever possible.

12. Engine architecture

Engines should expose stable capabilities to the rest of the platform.

Initial engine set:

1. Identity/Permission Engine 2. Object/Data Engine 3. Relationship Engine 4. Event Engine 5. Workflow Engine 6. Knowledge Engine 7. Content Engine 8. View/UI Engine 9. Communication Engine 10. Integration Engine 11. Analytics Engine 12. Automation/Scheduling Engine 13. AI/Intelligence Layer

Not every engine needs to be a separate service. The distinction is architectural and conceptual first.

13. New engines

The platform must support future engine introduction.

Before creating a new engine, determine whether the requirement can be represented through existing primitives.

A new engine is justified when:

Engine creation should be:

AI can assist in designing an engine, but production engine changes should pass controlled validation.

14. Application generation

An application is a projection of the business model.

The system should be able to generate or configure:

The same underlying objects should be usable by multiple capabilities.

For example, the Customer object may appear in:

This is a major reason for maintaining a shared business model.

15. AI architecture

AI should sit above the business platform rather than replace it.

AI receives controlled access to:

AI may return:

The platform validates and executes these outputs.

16. Evolution engine

A future Evolution/Optimisation layer should monitor:

It generates candidate improvements.

Example:

> Observation: users manually create the same three tasks after every sale.

> Suggestion: create an automated post-sale workflow.

> Approval: manager approves.

> Change: workflow becomes active.

> Measurement: compare process duration before and after.

This creates a closed improvement loop without requiring autonomous uncontrolled modification.

17. Architectural test

For any proposed feature, ask:

1. Can the data be represented using the existing id + type + value primitive? 2. Can an existing type definition express the required structure and validation? 3. Can existing relationships represent the required connections? 4. Can an existing engine support the behaviour? 5. Is it simply new configuration or a new type? 6. Does it belong in a reusable capability? 7. Does it genuinely require a new engine?

This should prevent premature proliferation of modules and engines.