← Back to directory

00-idiosyncrasy-combined-handoff.md

archive/architecture-sources/00-idiosyncrasy-combined-handoff.md · 32.7 KB · 2026-11-02 12:48

Idiosyncrasy — Updated Architecture & Product Documentation

Provisional v0.4 — September 2026

This combined handoff contains the current product, technical architecture/data, and MVP documentation.

Idiosyncrasy — Product Definition & Core Principles

Provisional v0.2 — September 2026

1. Product definition

Idiosyncrasy is a business-adaptive application platform: software that models how a business actually works and provides the applications, workflows, knowledge, automation and interfaces required to operate it.

It is intentionally holistic. It should progressively provide the capabilities a business needs rather than forcing the customer to assemble a large collection of disconnected SaaS products.

The customer should not need to become a software developer, database designer or prompt engineer.

The core proposition is:

> Software that learns your business, rather than making your business learn the software.

Idiosyncrasy should be capable of starting with a small business model and progressively expanding it as the business grows, changes and discovers new requirements.

2. The four primary product principles

2.1 Ease of use

Business users describe needs in business language.

They should not need to understand:

Complexity belongs inside the platform.

AI may help interpret intentions, but the resulting system must remain understandable, inspectable and editable.

2.2 Not AI-dependent; AI-supported

AI is an optional intelligence layer, not the foundation of the business system.

The deterministic platform must continue to operate if:

AI can assist with:

The business model, data, workflows and core application behaviour must remain platform-owned and deterministic.

2.3 Self-optimising, suggesting and evolving

Idiosyncrasy should observe how the business operates and identify opportunities to improve it.

The default evolutionary loop is:

> Observe → Understand → Suggest → Approve → Implement → Measure

Suggestions may concern:

Idiosyncrasy should normally propose significant changes rather than silently making them.

2.4 Inherent growing knowledge

Idiosyncrasy must develop persistent institutional memory for the business.

This is broader than structured data and broader than AI memory.

The platform must be able to retain:

Knowledge must have provenance and, where appropriate, status, ownership, applicability and dates.

The longer a business uses Idiosyncrasy, the more accurately the platform should understand that business.

3. Structured retrieval principle

Idiosyncrasy should retrieve business information by exploiting the structure of the Business Graph before relying on expensive semantic search. Because every addressable object has a type, object type is a guaranteed first-class retrieval dimension, but it is not the only one. Relationships, state, time, provenance, ownership, permissions and other deterministic characteristics should progressively constrain retrieval before semantic/vector techniques are used.

This allows Idiosyncrasy to remain fast, predictable and scalable while still supporting natural-language and knowledge-rich queries.

3. Holistic platform principle

Idiosyncrasy should aim to contain the major capabilities a business needs.

Initial capability areas may include:

This is not a fixed module list.

The platform must be extensible.

A capability is preferably assembled from common engines and primitives rather than becoming a completely isolated application.

4. Universal data primitive

Idiosyncrasy uses one foundational data model throughout the platform. All persistent and addressable platform data is represented using the same primitive:

Object = {
    id,
    type,
    value
}

This is an architectural rule, not merely a convenient storage format. Business objects, configuration, knowledge, workflows, events, rules, policies, goals, decisions, relationships, UI definitions, integration records and other addressable data must adhere to the same id + type + value model.

The platform must not introduce separate bespoke object schemas for individual modules or conceptual layers merely because the data has a different business meaning. Meaning is provided by type, the structure of value, relationships, type definitions, behaviour and context.

This creates a continuously extensible model: new business concepts can be introduced as new types without changing the fundamental data architecture. New capabilities should therefore extend the platform's vocabulary and behaviour rather than create parallel data universes.

The primitive does not mean that all values are unstructured. Type definitions may describe valid value structure, validation, relationships, permissions, lifecycle and behaviour. The important distinction is that these definitions are themselves addressable data using the same primitive.

Architectural rule

> There is one fundamental object model in Idiosyncrasy. All platform data uses id + type + value. No module may introduce a competing foundational data structure without an explicit architectural decision.

5. The platform versus modules

The platform should distinguish between:

Core primitives

Reusable concepts such as:

Engines

Reusable execution/configuration systems such as:

Capabilities

Business-facing systems assembled from the engines:

Applications

The actual interfaces and experiences presented to a particular business.

This hierarchy prevents the architecture becoming a collection of unrelated modules.

6. Extensibility and new capabilities

Idiosyncrasy must not assume that every future business requirement is known in advance.

When a new requirement appears:

Level 1 — Existing capability

Use existing functionality.

Level 2 — New configuration

Construct the capability from existing primitives and engines.

Level 3 — New engine

If the requirement genuinely cannot be represented by the existing architecture, introduce a new reusable engine.

A new engine should become a platform capability rather than a one-off customer hack wherever possible.

The platform should therefore be capable of evolving its own capability set over time.

AI may assist humans in designing new configurations and engine definitions, but foundational engine changes should be governed and testable.

7. Business ownership

The customer's business model is a first-class asset.

Idiosyncrasy should make the business representation:

AI-generated configuration must not become an opaque black box.

8. Competitive philosophy

Idiosyncrasy should not compete primarily on:

> "We have AI that can build an app."

AI coding tools increasingly make application construction accessible.

The stronger proposition is:

> Idiosyncrasy provides the persistent business model, application runtime, workflow system, knowledge layer, integrations and evolutionary mechanism that allow a business to have software which continuously adapts to it.

The customer is buying an operating platform, not a code generator.

9. Long-term product ambition

The intended trajectory is:

> Business description → Business model → Applications → Operations → Knowledge → Observation → Suggestions → Evolution

The platform should progressively become the digital operating representation of the business without requiring the business to maintain a software department.

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.

Idiosyncrasy — Initial Engines, Workflows & MVP

Provisional v0.2 — September 2026

1. Development strategy

Build Idiosyncrasy from the bottom up.

Do not start by building a large collection of disconnected business modules.

First create the reusable platform engines. Then use them to build the first visible business capabilities.

The MVP should prove the platform's central thesis:

> A business can be modelled once, and multiple useful applications and workflows can operate against that model.

2. Foundational data rule

Before the engines below are implemented, the MVP must establish the universal id + type + value primitive. This primitive applies to all persistent and addressable data in the platform.

The MVP must not create separate data models for CRM records, knowledge items, workflows, events, configuration, business-model definitions, UI definitions, relationships or other capability-specific concepts. All such concepts are represented as typed addressable objects using the same primitive.

Type definitions provide structure and validation; relationships provide graph connectivity; engines provide reusable behaviour. This separation is fundamental to Idiosyncrasy's continuous extensibility.

A new business concept should normally require a new type/configuration, not a database schema change. A new engine is justified only when genuinely new reusable execution behaviour is required.

2.1 Retrieval architecture requirement

The MVP must establish structured retrieval as a platform capability, not as an AI-only search feature. The type property of every universal object is a first-class indexing and retrieval dimension. Retrieval must use object type to narrow candidate sets before expensive semantic/vector retrieval.

The retrieval system should also exploit relationships, state, time, provenance, ownership, permissions and other deterministic characteristics where available. Semantic retrieval should operate over the already-constrained candidate set whenever possible.

This prevents the platform from treating the Business Graph as an undifferentiated corpus and provides a scalable path as the number and variety of object types grows.

3. Initial engine priority

Phase 1 — Foundation

Identity/Permission Engine

Required for:

Object/Data Engine

Required for:

Relationship Engine

Required for:

Event Engine

Required for:

Workflow Engine

Required for:

Phase 2 — Knowledge and interface

Knowledge Engine

Required for:

View/UI Engine

Required for:

Content Engine

Required for:

Phase 3 — Business operation

Communication Engine

Required for:

Integration Engine

Required for:

Analytics Engine

Required for:

Phase 4 — Intelligence

AI/Intelligence Layer

Required for:

Evolution/Optimisation Layer

Initially lightweight; progressively expanded.

4. Initial business capabilities

The MVP should not attempt to finish every module.

It should prove a representative cross-section.

Recommended first capabilities:

Business Core

CRM

Workflow

Knowledge

CMS

Marketing

These capabilities must share the same underlying id + type + value objects and engines. No capability may create a parallel foundational data model.

5. Example cross-system workflow

A useful MVP demonstration:

> Website enquiry submitted

1. Form creates Enquiry object. 2. Enquiry relates to Person/Organisation. 3. Event enquiry.received is emitted. 4. Workflow evaluates enquiry. 5. Customer record is created or matched. 6. Sales opportunity is created. 7. Task is assigned. 8. Confirmation email is sent. 9. Interaction is recorded. 10. Knowledge can be attached if useful. 11. Dashboard metrics update. 12. AI may optionally summarise or classify the enquiry.

This single workflow demonstrates the value of a shared platform.

6. Knowledge workflow

Example:

> User uploads a PDF containing the company's pricing policy.

1. Document object is created. 2. Knowledge Engine extracts/indexes content. 3. Knowledge item is associated with the pricing policy. 4. Source and provenance are recorded. 5. AI can answer questions using the authorised knowledge. 6. Workflow rules can reference the policy where appropriate. 7. When the policy changes, the old knowledge remains historically identifiable.

7. Self-optimisation workflow

Example:

1. System observes repeated manual actions. 2. Evolution layer detects a pattern. 3. Pattern is assessed against permissions and thresholds. 4. Idiosyncrasy proposes an optimisation. 5. User reviews the proposed change. 6. User approves or rejects it. 7. If approved, configuration is updated. 8. System measures the result. 9. Outcome becomes part of the business knowledge/history.

8. Future capability creation

Suppose a customer requests equipment servicing.

First ask:

> Can this be represented using existing Objects + Relationships + Workflows + Views?

If yes, create:

plus workflows and views.

No new engine is necessary.

If a large number of businesses later require specialist service scheduling, route optimisation and technician dispatch, a reusable Service Management capability may be introduced.

Only if the underlying behaviour cannot reasonably be supported by existing engines should a new engine be considered.

9. Human-operated first

Every major capability should be capable of operating without AI before AI is deeply integrated into it.

For example:

Marketing

First build:

Then add AI:

CMS

First build:

Then add AI:

Workflows

First build:

Then add AI:

This keeps the platform useful and reliable independently of AI.

10. MVP success criteria

The MVP is successful if it demonstrates that:

1. A business can be represented without bespoke application code. 2. All persistent/addressable platform data uses the same id + type + value primitive. 3. Objects and relationships are reusable across capabilities. 4. Workflows execute deterministically. 5. Knowledge can exist outside structured data. 6. Knowledge can be related to business objects. 7. Interfaces can be generated/configured from the business model. 8. A new capability can be assembled from existing engines. 9. AI can assist without being required. 10. The system can suggest improvements. 11. Configuration remains readable and editable by humans and AI.

11. What not to build initially

Avoid:

The first objective is to prove the platform architecture.

12. Long-term expansion model

The product should grow in this direction:

Foundation → Business Model → Knowledge → Workflows → Interfaces → Core business capabilities → Integrations → AI assistance → Optimisation → New capabilities → New reusable engines where genuinely necessary

The platform becomes more capable for every customer without becoming architecturally dependent on any individual customer.