@collective-intelligence/extensions-sdk-frontend 0.2.6 → 0.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -0
- package/docs/guide/ai/index.md +349 -0
- package/docs/guide/data/connectors.md +204 -0
- package/docs/guide/data/datasets.md +156 -0
- package/docs/guide/data/knowledge.md +211 -0
- package/docs/guide/develop/extensions.md +208 -0
- package/docs/guide/develop/external-apps.md +245 -0
- package/docs/guide/develop/sdks.md +233 -0
- package/docs/guide/index.md +78 -0
- package/docs/guide/platform/access.md +244 -0
- package/docs/guide/platform/architecture.md +142 -0
- package/docs/guide/platform/entrypoints.md +236 -0
- package/docs/guide/scenarios/index.md +107 -0
- package/docs/guide/template/index.md +276 -0
- package/docs/guide/template/state-machines.md +294 -0
- package/package.json +4 -4
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Choosing primitives
|
|
2
|
+
|
|
3
|
+
Questions, criteria and scenario patterns for picking the CI primitives a demo needs.
|
|
4
|
+
|
|
5
|
+
A customer scenario reaches the demo team as a story, such as a sales desk that qualifies leads or a back office that reads uploaded documents. This page gives the criteria that turn such a story into CI primitives. The [template](../template/index.md) is one finished answer, a small sales CRM with Lead and Opportunity schemas in Knowledge, an external application for the web app, a convert-lead workflow, a lead qualifier agent and a Sales desk Studio app.
|
|
6
|
+
|
|
7
|
+
Some screens need no primitive at all. The template's public intake form posts to an API inside the web app, and that API keeps requests in memory until you replace its store with a database layer.
|
|
8
|
+
|
|
9
|
+
## Decision path
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart TD
|
|
13
|
+
S[Demo scenario] --> Q1{Where does the data live?}
|
|
14
|
+
Q1 -->|In CI| Q2{Who edits it?}
|
|
15
|
+
Q2 -->|People, agents and workflows| K[Knowledge schema]
|
|
16
|
+
Q2 -->|Nobody, rows are read and aggregated| MD[Managed dataset]
|
|
17
|
+
Q1 -->|Customer database or warehouse| Q3{Must it stay there?}
|
|
18
|
+
Q3 -->|Yes| XD[External dataset or Gateway]
|
|
19
|
+
Q3 -->|Agents need a few fields| K
|
|
20
|
+
Q1 -->|Only the app needs it| APP[App-owned storage]
|
|
21
|
+
S --> Q4{Is it files?}
|
|
22
|
+
Q4 -->|People browse, agents search| DOC[Documents]
|
|
23
|
+
Q4 -->|One extraction step| WF[Workflow]
|
|
24
|
+
S --> Q5{Does it come from a SaaS?}
|
|
25
|
+
Q5 -->|Recurring import| CON[Connector]
|
|
26
|
+
S --> Q6{Deterministic or open-ended?}
|
|
27
|
+
Q6 -->|Fixed steps| WF
|
|
28
|
+
Q6 -->|Open-ended| AG["Agent + Skill"]
|
|
29
|
+
Q6 -->|One fixed rule| T[Tool]
|
|
30
|
+
S --> Q7{Does a side effect need approval?}
|
|
31
|
+
Q7 -->|In chat or a Skill form| TA[Tool with approval]
|
|
32
|
+
Q7 -->|Inside a process| AN[Workflow approval node]
|
|
33
|
+
S --> Q8{Who uses the UI?}
|
|
34
|
+
Q8 -->|Customers outside CI| EA[External app]
|
|
35
|
+
Q8 -->|Staff inside Studio| SA[Studio app]
|
|
36
|
+
S --> Q9{Must agents call existing backend logic?}
|
|
37
|
+
Q9 -->|Yes| GW["Gateway + remote tool collection"]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The questions are independent, so one scenario answers several of them and the demo combines the results. The sales CRM answers the data question with Knowledge schemas, the work question with a workflow and an agent, and the UI question twice: customers use the external app and staff use the Studio app.
|
|
41
|
+
|
|
42
|
+
## Criteria
|
|
43
|
+
|
|
44
|
+
| Signal in the scenario | Primitive | Why | Watch out for |
|
|
45
|
+
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| People in the app or Studio, agents and workflows all read and edit the records | [Knowledge schema](../data/knowledge.md) | One typed record per real thing, with relations, search and data policies that every surface shares | Measurements, events and other high-volume rows belong in a dataset, so do not create one record per row |
|
|
47
|
+
| Rows that people read and aggregate, such as a CSV or Excel export with trends | [Managed dataset](../data/datasets.md) | CI stores the typed rows and answers records, aggregate and time-series queries | A dataset declared with no data policy grants access to nobody, and deploy does not import the file |
|
|
48
|
+
| A warehouse such as Microsoft Fabric or Databricks holds the data, and it must stay there | [External dataset](../data/datasets.md) | CI queries the source live and keeps no copy | Queries take no SQL, and a provider outage fails the query with no fallback |
|
|
49
|
+
| The customer's own app and database keep the records | [Gateway](../develop/external-apps.md) | CI reaches the resources, dataset queries and operations that the customer server declares | The Gateway exposes only what its definition lists and never creates CI schemas |
|
|
50
|
+
| The app database is the authority, but agents need some of its fields | [Knowledge schema](../data/knowledge.md) with a projection | Only the needed, non-personal fields leave the app | Decide field by field what may leave; personal data stays in the app database |
|
|
51
|
+
| Files that people browse and agents search | [Documents](../data/knowledge.md#documents-and-knowledge) in a Document Collection | Collections hold folders, versions and permissions per path, and a connected collection stays in sync with a drive | A [Documents connector](../data/connectors.md) sync creates no Knowledge records, and new files become searchable only after indexing |
|
|
52
|
+
| A file that feeds one extraction step and nothing else | Stored file passed to a [workflow](../ai/index.md) | The workflow takes the file as `storageFileId` and returns extracted values | Use Documents instead when people must find the file later |
|
|
53
|
+
| A SaaS tool or SQL database that the demo imports from on a schedule | [Knowledge connector](../data/connectors.md) | A connector instance maps source fields to Knowledge schemas and runs full or delta imports | Installing the instance imports nothing until a schedule or a manual trigger runs, and SQL delta imports need a watermark column |
|
|
54
|
+
| A fixed sequence such as extract, check, create and notify | [Workflow](../ai/index.md) | A graph of steps with triggers, approvals and typed output, where a prompt node covers one bounded AI step | Every triggered workflow needs a service principal as its run-as identity |
|
|
55
|
+
| Open-ended work such as answering questions, finding matches or qualifying | [Agent with a Skill](../ai/index.md) | The agent picks its path from what it finds and returns typed output inside stated boundaries | A Skill can use only tools that its agent also allows, so the agent lists the Skill's tools again |
|
|
56
|
+
| A rule that must give the same answer every time | [Tool](../ai/index.md) | Code computes the result, and the agent explains it | An agent can call the tool only when its `usageScopes` include `"automation"` |
|
|
57
|
+
| A side effect that a person must approve | [Tool binding with approval](../ai/index.md), or a workflow approval node | `approval: "always"` or a named rule pauses the call until someone decides | A named rule must exist in the Organization before install, and an unattended agent run approves by default |
|
|
58
|
+
| Customers or members use the UI outside CI | [External application](../develop/external-apps.md) | The web app keeps its own UI and reaches CI through its BFF with a sealed-cookie session | The app takes no OAuth scopes; its app gate and Max Privileges limit what users can do |
|
|
59
|
+
| Staff work inside Studio | [Studio app](../develop/extensions.md) | Built-in views show schema records without code, and custom widgets cover what they cannot show | A Declared Studio App is read-only in the Studio builder and changes only with a new package release |
|
|
60
|
+
| Agents must call logic that an existing backend already implements | [Gateway with a remote tool collection](../develop/external-apps.md) | The logic stays in the customer service and reaches agents as tools | CI signs a short-lived token for every Gateway call, and browser cookies never authorize one |
|
|
61
|
+
| Some people may see or do things that others may not | [Access Profiles and Access Grants](../platform/access.md) | Capabilities and Knowledge data policies decide actions and visible records, and grants give them to Groups | Knowledge data policies do not cover datasets, which list their principals in their own policy |
|
|
62
|
+
| Logs, counters or sessions that only the app needs | App-owned storage behind the app API | No CI user or agent reads this data | A staff page that shows it needs its own credential in the app |
|
|
63
|
+
|
|
64
|
+
## Workflow, agent or tool
|
|
65
|
+
|
|
66
|
+
A workflow prompt node and an agent both call a model, which makes this the choice newcomers most often get wrong. A prompt node fits a step with fixed input and output shapes at a fixed place in a sequence, while an agent fits work whose path depends on what it finds. A rule that must give the same answer every time belongs in a tool that the agent or Skill calls. The template's lead score tool adds named points ("Work email" 40, "Email domain matches the company" 30, "Qualified by sales" 30), and the lead qualifier agent submits that score with a one-sentence rationale. In the demos built so far, document extraction, enrichment and approvals ran as workflows, and question answering, matching and qualification ran as agents.
|
|
67
|
+
|
|
68
|
+
An agent that must not change data says so in `behavioralBoundaries`. The lead qualifier declares "Never change a Lead or create an Opportunity". When an agent should help with a change, let it propose the change and let the person apply it with a button in the app.
|
|
69
|
+
|
|
70
|
+
A workflow's trigger follows from who or what starts the work. A `schedule` trigger runs it on a clock, `entity-created` and `entity-updated` react to Knowledge changes, `external-application` lets the web app start it, and `on-demand` lets staff start it from Studio. The template's convert-lead workflow uses the `external-application` trigger and runs as the `convert-lead-runner` service principal. See [AI](../ai/index.md) for the full comparison of tools, Skills, agents and workflows.
|
|
71
|
+
|
|
72
|
+
## Approvals depend on the caller
|
|
73
|
+
|
|
74
|
+
In chat or a Skill form, a tool binding with `approval: "always"` or a named rule pauses the call until a person decides. A workflow pauses at an explicit approval node, and the approver decides from Studio notifications.
|
|
75
|
+
|
|
76
|
+
> **Warning:** An unattended agent run has no person to ask. When one of its tool bindings
|
|
77
|
+
> requires approval, CI approves the call by default and records that decision.
|
|
78
|
+
> If the demo must show a person approving, use chat, a Skill form or a workflow
|
|
79
|
+
> approval node.
|
|
80
|
+
|
|
81
|
+
## Scenario patterns
|
|
82
|
+
|
|
83
|
+
| Pattern | Primitives | Why |
|
|
84
|
+
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
85
|
+
| Sales CRM: staff qualify and convert leads that arrive through a public site | Lead and Opportunity [Knowledge schemas](../data/knowledge.md), an [external application](../develop/external-apps.md) with a BFF, the convert-lead [workflow](../ai/index.md), a lead qualifier agent with a Skill and a scoring tool, a Sales desk [Studio app](../develop/extensions.md) | People edit leads in the web app, staff read them in Studio, and the agent reads the same records. This is the [template](../template/index.md). |
|
|
86
|
+
| Data kept in the customer's database: the customer will not move its records | An external application and a [Gateway](../develop/external-apps.md) that exposes entity CRUD, a read-only dataset query and one business operation | CI reaches the records in place, so nothing is copied into Knowledge |
|
|
87
|
+
| Existing backend logic for agents: a service already implements the business rule | A Gateway with a remote tool collection | One service answers its own API, a CI operation binding and an agent tool, so its code never moves into a package |
|
|
88
|
+
| Document intake: people upload a document and expect structured data back | A stored file, a workflow started with `storageFileId`, an approval node, a Studio upload form | Extraction is a fixed sequence, so a workflow runs it. A website upload and a Studio upload form start the same workflow with the same input, and the app server settles the result. |
|
|
89
|
+
| Member portal: members sign in on a public site, and staff run the back office in Studio | Knowledge schemas with data policies, [Access Profiles](../platform/access.md), an external application, Studio apps, agents for member questions and matching, workflows for enrichment, scheduled jobs and approvals, app-owned storage for activity logs | Records that members and staff both edit live in Knowledge, where a data policy can hide a flagged record from everyone. An `entity-updated` workflow asks the app to re-read changed records, and activity logs stay in the app database. |
|
|
90
|
+
| Collaborative tracker: several people edit plans, actions and comments at the same time | Knowledge schemas with relations, Realtime and optimistic writes in the external application | An edit in one window appears in the others without a reload ([state machines](../template/state-machines.md) shows how), and the first demo needs no AI primitive |
|
|
91
|
+
| App database as the authority: the app owns the records, but staff want AI advice | A Knowledge schema that holds a projection of non-personal fields, an advisory agent | Contacts and other personal data never leave the app, and staff decide what to do with the agent's advice |
|
|
92
|
+
| Pure mock demo: a first visual pitch before any integration | No CI primitive; a state machine with simulated saves in Effect | The screens can be shown before CI work starts, and CI primitives come later |
|
|
93
|
+
|
|
94
|
+
Connectors, datasets declared in a package and Document Collections appear in the criteria above because the platform supports them, but no shipped demo pattern uses them yet.
|
|
95
|
+
|
|
96
|
+
Demos built from the template started with Knowledge schemas, access and an external application, and they added agents and workflows only where the scenario asked for them; one demo shipped with no CI primitive at all.
|
|
97
|
+
|
|
98
|
+
## Related pages
|
|
99
|
+
|
|
100
|
+
- [Knowledge](../data/knowledge.md)
|
|
101
|
+
- [Datasets](../data/datasets.md)
|
|
102
|
+
- [Connectors](../data/connectors.md)
|
|
103
|
+
- [AI](../ai/index.md)
|
|
104
|
+
- [External apps](../develop/external-apps.md)
|
|
105
|
+
- [Extensions](../develop/extensions.md)
|
|
106
|
+
- [Access](../platform/access.md)
|
|
107
|
+
- [The template](../template/index.md)
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
# The solution template
|
|
2
|
+
|
|
3
|
+
What you get from next-effect-app, where each piece of code goes, and how to take a new demo from local dev to an installed package.
|
|
4
|
+
|
|
5
|
+
`next-effect-app` is the starting point for every demo. It is a bun and Turborepo monorepo with one Next.js 16 App Router web app (`apps/web`) and one Extension Package declaration (`apps/extensions`). You start a demo by generating a new repository from it with **Use this template** on GitHub. Its example features are patterns to copy: a demo keeps their shape and replaces their content with the customer's domain.
|
|
6
|
+
|
|
7
|
+
## What you get
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
apps/
|
|
11
|
+
web/ # @acme/web Next app: routes, composition, Data Sources, app API and BFF instances
|
|
12
|
+
extensions/ # @acme/extensions Extension Package declaration (composition root)
|
|
13
|
+
packages/
|
|
14
|
+
organization/acme/ # @acme/organization package identity, access, groups, external application
|
|
15
|
+
features/intake/ # @acme/intake lead intake: API, store, XState flow, views
|
|
16
|
+
features/lead-conversion/ # @acme/lead-conversion convert-lead workflow and browser flow
|
|
17
|
+
features/lead-qualification/ # @acme/lead-qualification lead qualifier agent, Skill, tool, Studio widget
|
|
18
|
+
entities/lead/ # @acme/lead Lead contract, CI schema, Lead API, Read Port, Realtime, views
|
|
19
|
+
entities/opportunity/ # @acme/opportunity Opportunity contract, CI schema, views
|
|
20
|
+
modules/identity/ # @acme/identity CI federated auth, CI runtime, principal, login providers
|
|
21
|
+
modules/app-api/ # @acme/app-api typed package API client, QueryClient, ApiPrefetch
|
|
22
|
+
modules/ui/ # @acme/ui shadcn/ui primitives, AI Elements, theme, workspace-kit
|
|
23
|
+
tooling/config/ # @acme/config shared TypeScript base config
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Intake is a form with an XState flow and an app API that keeps its data in an in-memory store. Lead conversion is a Fixed workflow started by a single-action task. Lead qualification is an agent with a Skill, a tool and a Studio widget. The repository has no docs wiki, no infra folder and no generated client code, because the browser derives each typed client from its package `HttpApi` at runtime. It also ships an agent harness: an `AGENTS.md` per scope, and `.agents/` with skills, rules and lint scripts.
|
|
27
|
+
|
|
28
|
+
## Tiers and the import rule
|
|
29
|
+
|
|
30
|
+
Every package lives at `packages/<tier>/<name>`, keeps a flat name (`@acme/<name>`) and has exactly one `tier:*` tag in its own `turbo.json`. The six tiers, from top to bottom, are `app` (the composition roots), `organization` (package identity, access, groups, external application and deploy order), `features` (one user-visible capability each), `entities` (one business entity each), `modules` (business-agnostic machinery) and `tooling` (the shared tsconfig base).
|
|
31
|
+
|
|
32
|
+
```mermaid
|
|
33
|
+
flowchart TD
|
|
34
|
+
web["apps/web"]
|
|
35
|
+
ext["apps/extensions"]
|
|
36
|
+
org["organization<br/>@acme/organization"]
|
|
37
|
+
subgraph features["features"]
|
|
38
|
+
f1["intake"]
|
|
39
|
+
f2["lead-conversion"]
|
|
40
|
+
f3["lead-qualification"]
|
|
41
|
+
end
|
|
42
|
+
subgraph entities["entities"]
|
|
43
|
+
e1["lead"]
|
|
44
|
+
e2["opportunity"]
|
|
45
|
+
end
|
|
46
|
+
subgraph modules["modules"]
|
|
47
|
+
m1["identity"]
|
|
48
|
+
m2["app-api"]
|
|
49
|
+
m3["ui"]
|
|
50
|
+
end
|
|
51
|
+
tooling["tooling<br/>config"]
|
|
52
|
+
web --> org
|
|
53
|
+
ext -->|"passes packageComponents to declarePackage"| org
|
|
54
|
+
org -->|"composes CI declarations in deploy order"| features
|
|
55
|
+
features --> entities
|
|
56
|
+
entities --> modules
|
|
57
|
+
modules --> tooling
|
|
58
|
+
f1 -.-|"never imports"| f2
|
|
59
|
+
e1 -.-|"never imports"| e2
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Imports point down the tiers and may skip a tier. Inside one tier, only modules and tooling packages import each other. A feature never imports another feature and an entity never imports another entity. When two of them must work together, a page in `apps/web` connects them.
|
|
63
|
+
|
|
64
|
+
The arrows are real configuration. The root `turbo.json` lists, for each tag, the tags it may depend on, and `bunx turbo boundaries` fails the build on a wrong import:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
"tier:features": { "dependencies": { "allow": ["tier:entities", "tier:modules", "tier:tooling"] } },
|
|
68
|
+
"tier:entities": { "dependencies": { "allow": ["tier:modules", "tier:tooling"] } },
|
|
69
|
+
"tier:modules": { "dependencies": { "allow": ["tier:modules", "tier:tooling"] } }
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Workspaces import each other by package name and exported subpath, such as `@acme/lead/views`, and never by relative path.
|
|
73
|
+
|
|
74
|
+
## Package subpaths
|
|
75
|
+
|
|
76
|
+
A feature or entity package exposes only the subpaths it needs. Each subpath is a folder under `src/` with one `index.ts` and one `exports` entry in `package.json`.
|
|
77
|
+
|
|
78
|
+
| Subpath | Holds | Imported by |
|
|
79
|
+
| ---------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
|
80
|
+
| `domain` | Effect Schema models, resource contracts, schema FQNs, pure rules | every other subpath and other packages |
|
|
81
|
+
| `ci` | CI declarations (extensions SDK) as factories over organization handles | `@acme/organization` |
|
|
82
|
+
| `api` | the package `HttpApi` under `/api/app`, its groups and tagged errors | `server`, `headless`, the app API composition |
|
|
83
|
+
| `server` | the route Layer of the package `HttpApi` and its services | `apps/web/src/server` only |
|
|
84
|
+
| `headless` | typed client, query options, XState machines, entity bindings, Realtime topics and hooks, simulated sources | `views` and the app |
|
|
85
|
+
| `views` | wired React views on `@acme/ui`; feature parts enter through slots | the app |
|
|
86
|
+
|
|
87
|
+
Inside a package the subpaths also have a direction. `domain` imports no other subpath, `ci` imports neither `headless` nor `views`, and `headless` and `views` never import `server`. That keeps server code out of the browser bundle and keeps CI declarations free of React.
|
|
88
|
+
|
|
89
|
+
Each template package exposes a different set:
|
|
90
|
+
|
|
91
|
+
| Package | Subpaths |
|
|
92
|
+
| -------------------------- | ------------------------------------- |
|
|
93
|
+
| `@acme/lead` | `domain ci api server headless views` |
|
|
94
|
+
| `@acme/opportunity` | `domain ci headless views` |
|
|
95
|
+
| `@acme/intake` | `domain api server headless views` |
|
|
96
|
+
| `@acme/lead-conversion` | `ci headless views` |
|
|
97
|
+
| `@acme/lead-qualification` | `ci` |
|
|
98
|
+
|
|
99
|
+
`@acme/lead-qualification` adds an agent, a Skill, a tool and a Studio widget, and all of that is CI-side behavior. Its single `./ci` subpath shows that you can ship an AI capability without writing any web code.
|
|
100
|
+
|
|
101
|
+
## Features take their audience as a parameter
|
|
102
|
+
|
|
103
|
+
A feature package must not import `@acme/organization`, because organization sits above it in the tiers. A feature that offers something to a group of users therefore takes that `audience`, and the application handle, as parameters. The organization package owns the groups and passes them in, then lists every component in deploy order, where each component follows the components it references:
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
export const packageComponents = [
|
|
107
|
+
crmDomain,
|
|
108
|
+
...leadComponents({ domain: crmDomain, version: VERSION }),
|
|
109
|
+
...opportunityComponents({ domain: crmDomain, version: VERSION }),
|
|
110
|
+
salesGroup,
|
|
111
|
+
acmeApplication,
|
|
112
|
+
crmCapabilities,
|
|
113
|
+
...crmPolicies,
|
|
114
|
+
repProfile,
|
|
115
|
+
managerProfile,
|
|
116
|
+
...salesGrants,
|
|
117
|
+
applicationTokens,
|
|
118
|
+
...convertLeadComponents({ application: acmeApplication, version: VERSION }),
|
|
119
|
+
...leadQualificationComponents({
|
|
120
|
+
application: acmeApplication,
|
|
121
|
+
audience: salesMembers,
|
|
122
|
+
version: VERSION
|
|
123
|
+
}),
|
|
124
|
+
salesDeskApp
|
|
125
|
+
]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Because the organization package owns the content, `apps/extensions/src/index.ts` only declares the package:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
export default declarePackage({
|
|
132
|
+
components: packageComponents,
|
|
133
|
+
hostedContributions: [/* the Lead score card Studio widget */],
|
|
134
|
+
manifest: packageManifest
|
|
135
|
+
})
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
[Extensions](../develop/extensions.md) describes each kind of declaration, and [Access](../platform/access.md) explains the Access Profiles and Access Grants in that list.
|
|
139
|
+
|
|
140
|
+
## The web app layers
|
|
141
|
+
|
|
142
|
+
Entity and feature code lives in packages. The web app keeps only routes, Composition, the sign-in gate, Data Sources and server instances, arranged in a fixed set of layers where each layer imports only the layers below it:
|
|
143
|
+
|
|
144
|
+
| Layer in `apps/web/src` | Holds |
|
|
145
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `app/` | route files only; each re-exports a Composition export, and `app/api/**` forwards to `server/<domain>/server` |
|
|
147
|
+
| `composition/` | `providers/` (global providers, Realtime providers) and `routing/` (access, shells, pages) |
|
|
148
|
+
| `features/` | app-local capabilities: their Data Sources (`remote/server.ts`) and `page-link/` |
|
|
149
|
+
| `entities/` | app-local entity machinery that several features need (the CI session), Data Sources of entity packages, `page-link/` |
|
|
150
|
+
| `server/` | beside the layers: one folder per domain, where `server.ts` (`server-only`) holds the process instance |
|
|
151
|
+
|
|
152
|
+
Only Composition imports a Data Source, and only Data Sources and `app/api/**` import a `server/<domain>/server.ts`. Peers still meet without importing each other: the CRM page template passes `ConvertLead` into the `selectionActions` slot of `LeadWorkspace` and `LeadAttachment` into its `editorActions` slot. Each page's owner gives its `{ label, path }` in `page-link/`, and shells and links read it, so no route path is written twice.
|
|
153
|
+
|
|
154
|
+
One Next app serves two server surfaces:
|
|
155
|
+
|
|
156
|
+
| Path | Handler | What it is |
|
|
157
|
+
| ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
158
|
+
| `/api/app/*` | `server/app-api/server` | the app API: the packages' Effect `HttpApi`s merged, OpenAPI at `/api/app/openapi.json`, Scalar docs at `/api/app/docs` |
|
|
159
|
+
| `/api/*` | `server/ci/server` | the CI SDK BFF: sign-in with a sealed cookie, Lead and Opportunity resource proxy, Realtime ticket and revalidate routes |
|
|
160
|
+
| `/api/leads/[id]/convert` | `server/ci/server` | the Fixed convert-lead workflow route |
|
|
161
|
+
|
|
162
|
+
The BFF holds the CI session in a sealed cookie and proxies resource calls, so the browser never holds a CI secret. [External applications](../develop/external-apps.md) covers the BFF in depth. The intake app API keeps its data in `IntakeStore.layerMemory`, and you replace that layer when a demo needs its own database.
|
|
163
|
+
|
|
164
|
+
## Start a new demo
|
|
165
|
+
|
|
166
|
+
1. Generate a repository with **Use this template**. In the new repository, delete the README "Contributing" section and `.github/workflows/close-pull-requests.yml`, which only matter in the template repository itself.
|
|
167
|
+
2. Rename the template for the customer. Replace the `@acme/` package scopes and the `acme.app.` FQNs, replace `https://acme.localhost` in `packages/organization/acme/src/application.ts` and `.env.example`, and replace the theme tokens and the sidebar brand in `apps/web/src/composition/routing/shells/workspace/app-sidebar.tsx`. Theme tokens live once, in `packages/modules/ui/src/styles/globals.css`.
|
|
168
|
+
3. Run it locally. The Overview and Lead intake pages work with no configuration, because the intake API keeps requests in memory:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
bun install
|
|
172
|
+
bun run dev:web # http://localhost:3000
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The CRM page needs a CI tenant.
|
|
176
|
+
|
|
177
|
+
4. Deploy the package to an Organization. `ci deploy` runs the whole release path in one command, as [Extensions](../develop/extensions.md) describes. The long path runs each step by hand:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
ci package build --declaration ./apps/extensions/src/index.ts --out apps/extensions/dist/release
|
|
181
|
+
ci package validate --archive apps/extensions/dist/release/release.tar \
|
|
182
|
+
--manifest apps/extensions/dist/release/manifest.json \
|
|
183
|
+
--package-manifest apps/extensions/dist/release/package-manifest.json
|
|
184
|
+
ci package publish --backend-url <url> \
|
|
185
|
+
--archive apps/extensions/dist/release/release.tar \
|
|
186
|
+
--manifest apps/extensions/dist/release/manifest.json \
|
|
187
|
+
--package-manifest apps/extensions/dist/release/package-manifest.json \
|
|
188
|
+
--idempotency-key <key>
|
|
189
|
+
ci package promote --backend-url <url> --release <release-id> --idempotency-key <key>
|
|
190
|
+
ci package install --backend-url <url> --organization <organization-id> \
|
|
191
|
+
--package acme.app.knowledge --release <release-id> --idempotency-key <key>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Running `package build` into a scratch folder and then `package validate` is the dry run for any change to the package.
|
|
195
|
+
|
|
196
|
+
5. Rotate the application secret. The package installs a confidential application without a secret, so an Organization administrator rotates one:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
curl -sS -X POST \
|
|
200
|
+
-H "authorization: Bearer <administrator-token>" \
|
|
201
|
+
-H "x-organization-id: <organization-id>" \
|
|
202
|
+
<url>/admin/organization/external-apps/<application-id>/credential/rotate
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Copy `apps/web/.env.example` to `apps/web/.env.local`. Store `clientSecret` as `CI_CLIENT_SECRET`, `application.clientId` as `CI_CLIENT_ID` and the application id as `CI_APPLICATION_ID`. Then set `APP_ORIGIN`, `CI_TENANT_URL`, `CI_ISSUER`, `CI_AUDIENCE`, `CI_ORGANIZATION_ID`, `SESSION_SECRETS` and `NEXT_PUBLIC_APPLICATION_ID`, which equals `CI_APPLICATION_ID` and is the only value the browser sees. `ci apps enroll --env-file apps/web/.env.local` writes the enrollment values for you. Management tokens never go to Next.
|
|
206
|
+
|
|
207
|
+
6. Add users to the Sales group. CI accepts a user's token only when the user holds the application gate, so nobody can sign in yet. An administrator adds each user to the Sales group (Sales rep profile) or to its `managers` subgroup (Sales manager profile).
|
|
208
|
+
7. Sign in over HTTPS. The sealed session cookie requires HTTPS, so serve the dev server through a local HTTPS proxy:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
portless acme bun run dev:web # https://acme.localhost
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
> **Warning:** The `./` in `--declaration ./apps/extensions/src/index.ts` is required.
|
|
215
|
+
> Without it, the CLI resolves the path like a module name and fails.
|
|
216
|
+
|
|
217
|
+
> **Note:** After each npm release of the CI packages, the template gets the released SDK
|
|
218
|
+
> versions pinned and one sync commit. A repository you generated earlier does
|
|
219
|
+
> not receive these updates by itself.
|
|
220
|
+
|
|
221
|
+
## What to change and what to keep
|
|
222
|
+
|
|
223
|
+
A new demo changes the organization package, the entities, the features, the theme and the origins. It keeps `modules/identity`, `modules/app-api`, the BFF and server wiring, the tier tags, the lint configuration and the harness files, because they hold no business logic. A new environment variable goes into `apps/web/.env.example`, `packages/modules/identity/src/server/env.ts`, `turbo.json` `globalEnv` and the README tenant section together.
|
|
224
|
+
|
|
225
|
+
## Checks that keep the structure honest
|
|
226
|
+
|
|
227
|
+
`@collective-intelligence/lint` is one Oxlint plugin named `ci-solution`. Extending `recommended` turns every rule on as an error:
|
|
228
|
+
|
|
229
|
+
| Rule | Checks |
|
|
230
|
+
| -------------------------------- | ---------------------------------------------------------------------------------- |
|
|
231
|
+
| `ci-solution/package-entrypoint` | an import of another package targets an entrypoint in its `package.json` `exports` |
|
|
232
|
+
| `ci-solution/subpath-imports` | imports between subpath folders follow the allowed direction |
|
|
233
|
+
| `ci-solution/subpath-entrypoint` | an import of another subpath folder targets its index file |
|
|
234
|
+
| `ci-solution/subpath-index` | every subpath folder has `index.ts` or `index.tsx` |
|
|
235
|
+
| `ci-solution/effect-subpath` | SDK Effect APIs come from the SDK `/effect` subpath |
|
|
236
|
+
| `ci-solution/no-run-in-view` | a view module calls no `fetch` and runs no Effect |
|
|
237
|
+
| `ci-solution/effect-actors` | XState side-effect actors are `fromEffect` actors |
|
|
238
|
+
| `ci-solution/effect-writes` | no module uses TanStack Query `useMutation`; writes run in `fromEffect` actors |
|
|
239
|
+
|
|
240
|
+
Each package has an `oxlint.local.ts` that extends the preset:
|
|
241
|
+
|
|
242
|
+
```ts
|
|
243
|
+
import { recommended as ciSolution } from "@collective-intelligence/lint"
|
|
244
|
+
import { defineConfig } from "oxlint"
|
|
245
|
+
|
|
246
|
+
export default defineConfig({
|
|
247
|
+
extends: [ciSolution],
|
|
248
|
+
overrides: [
|
|
249
|
+
{
|
|
250
|
+
files: ["**/*.proof.ts"],
|
|
251
|
+
rules: { "eslint/curly": "off", "jsdoc/check-tag-names": "off" }
|
|
252
|
+
}
|
|
253
|
+
]
|
|
254
|
+
})
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
The web app also runs a `frontend-layers` lint for layer order, domain entrypoints, folder names and the `no-peer-feature` and `no-peer-entity` rules. For coding agents, the template ships Codebase Rules in `.agents/rules/`, such as `web-layer-imports`, `ci-sdk-boundaries` and `ci-realtime-topics`, each with a path trigger and a task trigger. The day-to-day checks are:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
bun run check-types
|
|
261
|
+
bun run test
|
|
262
|
+
bunx turbo boundaries
|
|
263
|
+
bun run lint
|
|
264
|
+
bun run format:check
|
|
265
|
+
bun run build
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
When you change the Lead cache, a Lead write or Lead Realtime, also run `bun run check:models` in `packages/entities/lead`. [State machines](state-machines.md) explains what that command checks.
|
|
269
|
+
|
|
270
|
+
## Related pages
|
|
271
|
+
|
|
272
|
+
- [State machines](state-machines.md)
|
|
273
|
+
- [SDKs](../develop/sdks.md)
|
|
274
|
+
- [Extensions](../develop/extensions.md)
|
|
275
|
+
- [External applications](../develop/external-apps.md)
|
|
276
|
+
- [Access](../platform/access.md)
|