AISDL System Design#
A System is a software product or system. It has a name and a description explaining its business purpose, who uses it and what it enables them to do.
A System contains Data Collections, Audiences, Processes, Services, Secrets and Events. These resources form one connected design. Audiences execute Processes. Processes use Services to work with stored records, files, messages and other capabilities. Secrets identify confidential values or cryptographic material. Events carry information between asynchronous actions.
The System Design author owns the business scope, rules, structure and implementation. The specifications describe the available structures and programming interfaces; they do not prescribe a business solution or a resource count.
Design Scope#
System Access and Identity Management already exist and are managed separately by the runtime. They are outside the scope of the business System Design.
Execution tracking and audit are also provided by the runtime and are outside this design scope. Do not recreate them as business Collections or Processes. Business records still store the information required by the business action and its rules.
Provider administration, infrastructure logs and backup management are operational responsibilities. Soft deletion is the business record-preservation rule, not a claim that the underlying database cannot delete rows.
Design the business information, relationships, Processes and their behavior. Processes declare ordinary typed Inputs and implement business behavior using those Inputs. Each Process declares its incoming authentication method in Process.md; the runtime enforces it. Do not design login, identity administration or policies for managing Users, Roles or access grants. Business relationships and validation remain part of the design.
Resource Names#
Each resource has a name, unique within its resource type in the System Design. Names contain only ASCII letters, digits, underscores (_) and dashes (-), with no spaces, dots or other special characters. The author chooses these names and uses them exactly in filenames and references, including capitalization. Do not generate a separate resource id.
For example, a Collection and an Audience can both be named Customer, because their resource types differ. Two Collections cannot have the same name. A Process dependency on a Collection uses that Collection's exact name; a Process's audience reference uses the Audience's exact name. The Audience's Process list is derived from those references.
Resource names are filenames or folder names. Renaming a resource requires updating its filename or folder and every reference to that name, including code references where applicable. The author is responsible for uniqueness and consistent references. This rule applies to resource names, not descriptive text, Event subjects, configuration type identifiers or dotted property paths.
Required Reading#
Learning specifications explain how to describe a System. They are not files produced as part of a particular business System.
Read each specification and schema below in full for its stated purpose. This is required before continuing to System authoring. Follow their document references and read those documents too; do not leave them for later use. Long documents can be read in successive parts, but finish all parts before continuing. A document already read in full does not need to be read again when another reference points to it.
| Explanation | JSON schema | Meaning |
|---|---|---|
| System-Design.md | System-Design.schema.json | Read for the System and its manifest. Required before continuing. |
| Data-Collection.md | Data-Collection.schema.json | Read for stored records, fields, relationships and indexes. Required before continuing. |
| Audience.md | Audience.schema.json | Read for populations of people and the Processes they execute. Required before continuing. |
| Process.md | Process.schema.json | Read for business actions, Inputs, Outputs, dependencies, composition and App presentations. Required before continuing. |
| AISDL.md | No separate schema. | Read for the complete specification's organization. Required before continuing. |
| languages/aiscript/AIScript.md | Grammar in the document. | Read for functions, values, calculations, dates, Services and execution semantics. Required before continuing. |
| Service.md | Service.schema.json | Read for declared capabilities and their configuration. Required before continuing. |
| Secret.md | Secret.schema.json | Read for confidential values and cryptographic material referenced by the System. Required before continuing. |
| Event.md | Event.schema.json | Read for asynchronous facts, payloads and consumer Input mappings. Required before continuing. |
Each learning file is supplied under its exact filename together with its contents. A filename identifies the supplied specification; it does not mean a file has automatically been opened. JSON schemas define document structure. The accompanying Markdown explains the meaning and use of that structure.
Produced System Files#
A business System is produced as a folder, not as one large JSON document containing every resource.
system/
manifest.json
collections/
<collection-name>.json
audiences/
<audience-name>.json
processes/
<process-name>/
process.json
code.ais
services/
<service-name>.json
secrets/
<secret-name>.json
events/
<event-name>.json
The angle-bracket names above stand for the resource's exact name. For example, the Process ReadSupplier has processes/ReadSupplier/process.json and, when implemented in code, processes/ReadSupplier/code.ais. A composite has no code.ais of its own. Additional resources, such as email templates, can be referenced by Process code using System-relative paths.
Manifest#
manifest.json contains the System's name, description and optional global properties. It follows System-Design.schema.json:
{
"name": "Procurement",
"description": "Manage suppliers, purchase orders and approvals.",
"properties": {
"cacheNamespace": "Procurement",
"ordering": {
"limits": {
"maxLines": 500
},
"currencies": [
"EUR",
"USD"
],
"allowBackorders": false
}
}
}
The manifest does not embed resources, list their contents or contain runtime topology and Service credentials. Resource definitions are stored in their corresponding folders.
A System may have global properties. The author freely defines them in properties, using values, nested objects and arrays. Code reads them with property(path, fallback):
maxLines = property("ordering.limits.maxLines", 500)
The path starts inside properties. Confidential values belong in Secrets.
Data Collections#
A Data Collection is like a database table: it stores records with declared fields. It has a name, documentation, fields, relationships and indexes. Collections can reference each other to describe related business records.
Each collections/<collection-name>.json follows Data-Collection.schema.json. Data-Collection.md explains records, fields, record IDs, references, arrays, indexes and soft deletion.
Services#
A Service is a declared capability used by Process code. Services include database, HTTP, TCP, storage, cache, SMTP, messaging and SecretsProvider operations. A Service has a name, documentation, a type and configuration. It can be shared by all Audiences or assigned to particular Audiences.
A Local Memory Cache holds independent values in each JVM. A Shared Cache makes values available to multiple JVMs or machines using the same store and keys. Both are declared Services obtained through the declared Service name.
HTTP and TCP Services make outbound calls; incoming actions are Processes. A database Service accesses Collection records. Storage works with files and folders. SMTP sends email. Messaging transports Event payloads.
Each services/<service-name>.json follows Service.schema.json. Service.md explains each capability and its configuration, including Secret references. languages/aiscript/AIScript.md defines the calls made by Process code.
Secrets#
A Secret declares sensitive information or a provider key needed by the System. It describes its symbolic name, type and purpose, never its confidential value or installed provider location. A Secret can be a structured object. Services can require the whole Secret or particular properties of that object.
Process code obtains a declared Secrets Service by name, just like any other Service, and calls its methods. SecretsProvider names the underlying runtime interface, not a global AIScript object. Lookup locations and provider key identifiers are supplied at runtime through application properties whose names always start with security.secrets.. Code uses the declared symbolic names under that prefix; it does not choose physical paths or key identifiers or implement cryptography.
Each secrets/<secret-name>.json follows Secret.schema.json. Secret.md explains the types and runtime lookup convention. languages/aiscript/AIScript.md defines the provider function interfaces. Security provisioning and publication supply the required configuration separately from the business design.
Processes#
A Process performs a business action. It defines its typed Inputs and Outputs, dependencies, authentication method, documentation and implementation. Its required audience references exactly one Audience by name, including for internal, scheduled and message-driven work. Its optional channels lists the allowed invocation channels: omitted means all channels, and an empty array means none. Audience association does not enable a channel or grant access.
Process code uses the System's declared Services and AIScript. A coded Process references its separate .ais file. That file defines execute(input) and any helper functions. A composite instead identifies child Processes, their connections and Input/Output mappings.
Each processes/<process-name>/process.json follows Process.schema.json. For a coded Process, implementation.resource points to processes/<process-name>/code.ais, relative to the System root. Process.md explains the contract, invocation, composition and App presentation. languages/aiscript/AIScript.md defines the coding interfaces and execution rules.
The author provides the business Process definition and code, not the native endpoint specification. System Access and Identity Management are provided by the runtime.
Audiences#
An Audience represents a population of people who use the System, grouped by their business relationship to the organization operating it.
People with the same kind of business relationship belong to the same Audience, even when they work for different organizations. Differences in departments, responsibilities, or permissions do not create separate Audiences. Roles distinguish access to Processes within an Audience.
An Audience represents people, not software components or execution mechanisms. Automated Processes reference the Audience whose business work they support.
Each Audience's description explains who those people are and their business relationship to the operating organization. User, Role, and access-grant management are provided separately by the runtime and are outside System Design.
Each Process declares its Audience; these references identify the Audience's Processes.
Each audiences/<audience-name>.json follows Audience.schema.json. Audience.md explains participation, responsibilities and Process association.
Events#
An Event is a typed fact communicated asynchronously. It describes a subject, a producer, payload values and consuming Processes. Each consumer maps payload values to its Process Inputs. A messaging Service supplies transport.
Emitting an Event is not the same as completing its consumers. A direct Process call is a separate interaction and is preferred when it meets the need. Events are used when asynchronous communication is needed, not as a required layer around every action.
Each events/<event-name>.json follows Event.schema.json. Event.md explains payloads, Input mappings and execution meaning.
Process Apps#
A Process's optional presentation describes how people interact with its Inputs and Outputs. It can provide forms, rows, tabs, wizards, lookups, tables, cards, metrics, charts, graphs and file viewers. Actions invoke Processes or navigate to other Process presentations with mapped Inputs.
App presentations do not directly access Collections or Services. They call Processes, and their data mappings match the actual Process contracts. Business rules are implemented by the Processes; System Access and Identity Management are provided by the runtime.
Presentation properties are defined in Process.schema.json and explained in Process.md. They are stored with the Process definition, not in a second business implementation.
Documentation And Consistency#
Documentation explains each resource's purpose, its properties and its relationships. Process documentation describes rules, successful outcomes, errors and examples. Code comments explain implemented operations and important decisions. Applicable security or industry annotations describe actual controls and verified references; they do not establish certification by themselves.
The resources must agree. A Process stores information in declared Collection fields and follows their relationships. A related retrieval Process uses the same information. Event mappings match consumer Inputs. App bindings match Process Outputs. Service and Secret references identify declared resources.
Create each resource as a coherent whole. After writing or changing it, reconcile its definition, code, documentation and presentation with one another and with referenced resources. Templates are starting points, not finished content. Before finishing, verify the final deliverable, correct discrepancies and review again. Passing individual schemas is not sufficient; claim only checks actually performed. Keep the business design yours; use the exact documented interfaces to implement it.
Atomic Authoring#
Resources can be read or changed separately without resending the entire System. A Process definition and its code form one resource change and must be saved together. Related changes across resources form one grouped change when they need to take effect together.
The authoring interface must validate and save the submitted change completely or leave the previous saved version unchanged. Grouped changes are validated against the resulting combined design, including references between resources created in that same change. This is a required authoring behavior, not a guarantee supplied by the folder layout alone.
This folder convention defines the authored System. Runtime installation, publication and migration are separate operations.