@collective-intelligence/extensions-sdk 0.2.6 → 0.2.8
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 +3 -3
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Grants and permissions
|
|
2
|
+
|
|
3
|
+
How CI decides what a user, a Group, an app or an API key may do, and how to change it in the template.
|
|
4
|
+
|
|
5
|
+
CI uses one access model for people, Groups, apps, service principals and API keys. Capabilities name the operations, Access Profiles bundle capabilities, Access Grants give a profile to someone, and Knowledge Data Policies decide which records a capability opens. This model replaced the older organization roles, app roles, API key scopes and OAuth scopes. The Dashboard still labels an Access Profile as "Role", so read that word as "profile" wherever you meet it.
|
|
6
|
+
|
|
7
|
+
## The model in one diagram
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart LR
|
|
11
|
+
P["Principal<br/>user, Group, service principal,<br/>app server, app visitors"] --> G[Access Grant]
|
|
12
|
+
G --> AP[Access Profile]
|
|
13
|
+
AP --> C[Capabilities]
|
|
14
|
+
MP[Max Privileges] -. caps app tokens and API keys .-> C
|
|
15
|
+
C --> DP[Knowledge Data Policy]
|
|
16
|
+
DP --> R[Records the caller may read or write]
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
A grant gives exactly one profile to exactly one recipient. The profile holds capabilities, and a Knowledge Data Policy turns a capability into rows of one schema. Max Privileges never give anything: they cut what an app's user tokens or an API key may use, whatever the grants say.
|
|
20
|
+
|
|
21
|
+
| Term | What it is | Who declares it |
|
|
22
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
23
|
+
| Capability | An operation CI authorizes, with a stable `code`. A Switch is off or on. A Read/Manage capability is off, `read` or `manage`, and `manage` includes `read`. Capabilities form a tree, and holding a node gives every node below it, including nodes a later release adds. | The core and packages |
|
|
24
|
+
| Access Profile | A set of capabilities for one audience: `user`, `server` or `anonymous`. | The core (six built-in, read-only profiles) and packages |
|
|
25
|
+
| Access Grant | One profile given to one recipient. | Packages, or at runtime through the Dashboard, invitations, SSO and the server SDK |
|
|
26
|
+
| Max Privileges | The most an app's user tokens or an API key may use. | Packages |
|
|
27
|
+
| Knowledge Data Policy | A rule on one schema and one operation (`read` or `write`): a required capability, an optional `where`, and the fields it lets the caller read or write. | The core and packages only. Nobody edits a policy at runtime. |
|
|
28
|
+
| Resource Audience | Who an agent, Skill, tool, workflow or Studio app is offered to. Entries name users, Groups, profile holders, apps, the whole Organization or anonymous visitors. | Packages |
|
|
29
|
+
|
|
30
|
+
## How CI decides
|
|
31
|
+
|
|
32
|
+
Every grant only allows. No grant and no audience entry can deny, so a policy that must hide some records does it with a `where` clause. CI also checks each grant alone, for reads, updates and read masks. If one grant holds the capability and a second grant holds the right perimeter, the two halves never combine into one permission.
|
|
33
|
+
|
|
34
|
+
Through an app, the user's effective access is the union of their grants, each checked alone, cut down to the app's Max Privileges. A Sales manager who is also an Organization admin still cannot do through the app what the Max Privileges leave out. Dashboard, Studio and MCP sessions are not cut this way.
|
|
35
|
+
|
|
36
|
+
A grant change takes effect within 60 seconds. Every Organization-scoped response carries an `x-access-version` header, and a client that sees the value change refetches its access snapshot from `GET /me/access`.
|
|
37
|
+
|
|
38
|
+
> **Note:** A Studio user reads no Knowledge record until something opens it: a package
|
|
39
|
+
> policy, the built-in knowledge reader profile or a custom profile. A schema
|
|
40
|
+
> without a policy shows its members nothing. In the same way, a resource with
|
|
41
|
+
> an empty audience is offered to nobody.
|
|
42
|
+
|
|
43
|
+
## Memberships carry no role
|
|
44
|
+
|
|
45
|
+
An Organization membership links one user to one Organization and has one kind, `member` or `guest`. An external app usually creates guests. The membership itself gives no access, because access comes only from grants. Every former role is now a grant of the matching built-in profile, such as `core.profiles.organization-admin` or `core.profiles.knowledge-reader`.
|
|
46
|
+
|
|
47
|
+
Groups are the usual way to hand out grants. A grant to a Group reaches its members. With `coverage: "inherited"` it also reaches members of every subgroup, and with `coverage: "direct"` it stops at the Group itself.
|
|
48
|
+
|
|
49
|
+
## Declared and runtime grants
|
|
50
|
+
|
|
51
|
+
A package can declare Groups, capabilities, profiles, policies, Max Privileges and grants, and the install creates them in the Organization. The template declares a Sales Group with a Sales managers subgroup. A subgroup has no handle of its own, so a grant names it by its FQN, which is the parent FQN, a dot and the subgroup key:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
export const salesGroupFqn = "acme.app.groups.sales"
|
|
55
|
+
const managersKey = "managers"
|
|
56
|
+
/** A subgroup has no handle: a grant names it by FQN. */
|
|
57
|
+
export const salesManagersGroupFqn = `${salesGroupFqn}.${managersKey}`
|
|
58
|
+
|
|
59
|
+
export const salesGroup = declareOrganizationGroup({
|
|
60
|
+
definition: {
|
|
61
|
+
lifecycle: { deployMode: "upsert", readonly: true },
|
|
62
|
+
subgroups: [
|
|
63
|
+
{
|
|
64
|
+
description: "Sales managers of the Acme CRM.",
|
|
65
|
+
displayName: "Sales managers",
|
|
66
|
+
key: managersKey
|
|
67
|
+
}
|
|
68
|
+
]
|
|
69
|
+
},
|
|
70
|
+
manifest: { fqn: salesGroupFqn, version: VERSION },
|
|
71
|
+
presentation: {
|
|
72
|
+
description: "Sales team of the Acme CRM.",
|
|
73
|
+
displayName: "Sales"
|
|
74
|
+
}
|
|
75
|
+
})
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The package declares the Groups but never fills them. After install, an administrator adds people to Sales or Sales managers.
|
|
79
|
+
|
|
80
|
+
The template grants the Sales rep profile to Sales and the Sales manager profile to Sales managers, both with `inherited` coverage. Managers are also members of Sales through the tree, so a manager holds both grants. The lifecycle of each grant decides who owns it after install. The Sales grant uses `deployMode: "init_only"` with `readonly: false`, so an administrator can revoke it and a package update does not write it again. The managers grant uses `upsert` with `readonly: true`, so the package keeps it in place.
|
|
81
|
+
|
|
82
|
+
Runtime grants come from the Dashboard, invitations, SSO defaults and the provisioning API. An app's server manages them through `ci.access` in the server SDK. `sync` makes the runtime grants under one namespace match the list exactly:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
await ci.access.grants.sync({
|
|
86
|
+
grants: [
|
|
87
|
+
{
|
|
88
|
+
fqn: "clinic.patients.p-1001",
|
|
89
|
+
grantee: { user: { email: "patient@example.test" } },
|
|
90
|
+
profile: "clinic.profiles.patient"
|
|
91
|
+
}
|
|
92
|
+
],
|
|
93
|
+
namespace: "clinic.patients",
|
|
94
|
+
organizationId
|
|
95
|
+
})
|
|
96
|
+
// result = { created, updated, deleted, unchanged }: Access Grant FQNs.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The app's server acts only with the grants an administrator gave to it as `{ applicationServer }`. It creates and changes only its own guests, reads Groups without writing them, sends no invitations, and never touches a package-declared grant.
|
|
100
|
+
|
|
101
|
+
## Data policies narrow records
|
|
102
|
+
|
|
103
|
+
A capability opens a feature. A Knowledge Data Policy decides which records of one schema that capability reaches. The template generates two policies for each of its schemas: reading needs CRM `read`, and writing needs CRM `manage`.
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
declareAccessKnowledgeDataPolicy({
|
|
107
|
+
definition: {
|
|
108
|
+
capability: requires(capability, "manage"),
|
|
109
|
+
lifecycle: readonly,
|
|
110
|
+
operation: "write",
|
|
111
|
+
target,
|
|
112
|
+
},
|
|
113
|
+
manifest: { fqn: `acme.app.policies.${name}-write`, version: VERSION },
|
|
114
|
+
}),
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Several policies on the same schema and operation combine with OR. A `where` clause limits the rows, and `readableFields: { except: ["salary"] }` removes a field from the result. Read masks do not apply to search, embeddings or filters yet, so a masked value can still match a search. Each record the caller reads also carries `access.write`, which tells the UI whether this caller may change that record and lets a page hide the edit button row by row.
|
|
118
|
+
|
|
119
|
+
A profile can also declare Grant Axes, such as Company or Country, so that one grant reads "this profile, but only for Italy". The template uses no axes. See [Knowledge](../data/knowledge.md) for schemas, conditions and axes in policies.
|
|
120
|
+
|
|
121
|
+
## The app gate
|
|
122
|
+
|
|
123
|
+
Every external app has an app gate: a Switch capability at the root of the app's capability tree, with the app FQN as its code. CI accepts a user's token for the app only when one of the user's grants holds the gate, so a user with no such grant cannot sign in. Both template profiles hold it:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
export const managerProfile = declareAccessProfile({
|
|
127
|
+
definition: {
|
|
128
|
+
audience: "user",
|
|
129
|
+
capabilities: [
|
|
130
|
+
allow(accessGate(acmeApplication)),
|
|
131
|
+
allow(core.platform.knowledge),
|
|
132
|
+
allow(core.platform.agents),
|
|
133
|
+
allow(core.platform.workflows),
|
|
134
|
+
allow(crmCapabilities, "manage")
|
|
135
|
+
],
|
|
136
|
+
lifecycle: readonly
|
|
137
|
+
},
|
|
138
|
+
manifest: { fqn: "acme.app.profiles.manager", version: VERSION },
|
|
139
|
+
presentation: { displayName: "Sales manager" }
|
|
140
|
+
})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The Sales rep profile holds the same gate with `platform.knowledge`, `platform.agents` and CRM `read`. It leaves out `platform.workflows` and CRM `manage`.
|
|
144
|
+
|
|
145
|
+
The gate lets a user in. Max Privileges then limit what the app's user tokens may use, for every caller including tenant users:
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
export const applicationTokens = declareAccessMaxPrivileges({
|
|
149
|
+
definition: {
|
|
150
|
+
appliesTo: { applicationTokens: acmeApplication },
|
|
151
|
+
capabilities: [
|
|
152
|
+
allow(core.platform.knowledge),
|
|
153
|
+
allow(core.platform.agents),
|
|
154
|
+
allow(core.platform.workflows),
|
|
155
|
+
allow(crmCapabilities, "manage")
|
|
156
|
+
],
|
|
157
|
+
lifecycle: readonly
|
|
158
|
+
},
|
|
159
|
+
manifest: { fqn: "acme.app.max-privileges.user-tokens", version: VERSION }
|
|
160
|
+
})
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
> **Warning:** An app registered from the Dashboard or the CLI has no Max Privileges, so its
|
|
164
|
+
> user tokens can sign in and read no data at all. Declare the app in a package
|
|
165
|
+
> together with its Max Privileges when its tokens must read data.
|
|
166
|
+
|
|
167
|
+
Consent is a separate setting. `applicationConsent` (`inherit`, `ask` or `skip`) only decides whether the user sees an Allow and Deny panel. A user without a grant that holds the gate is refused under `skip` exactly as under `ask`. The [External apps](../develop/external-apps.md) page covers sign-in and consent in full.
|
|
168
|
+
|
|
169
|
+
## API keys and service principals
|
|
170
|
+
|
|
171
|
+
A service principal is a non-human identity, declared with `servicePrincipal({ fqn, groups, name, version })`. It holds only the grants that name it with `grantee: { servicePrincipal }`. The template's `convertLeadRunner` is a service principal with no Groups that the convert-lead workflow can run as.
|
|
172
|
+
|
|
173
|
+
An API key belongs to a service principal and is created with a Max Privileges template:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
ci api-keys upsert --principal <fqn> --name <name> --max-privileges <template-fqn>
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The template sets the ceiling, and the principal's grants decide what the key may do below it. A key without a template uses no capability, and no API key can manage API keys. CI shows the secret once.
|
|
180
|
+
|
|
181
|
+
> **Warning:** A run as a service principal asks no questions and decides no approvals. Tool
|
|
182
|
+
> approval gates do not stop it: CI approves unattended calls by default and
|
|
183
|
+
> records them without an actor. Plan for this before a demo drives an agent
|
|
184
|
+
> with an API key.
|
|
185
|
+
|
|
186
|
+
The template's server also reads Leads with the app's own credential (the Read Port on the [External apps](../develop/external-apps.md) page). The package declares no `{ applicationServer }` grant for it, so an administrator must give the app server read access to Leads after install.
|
|
187
|
+
|
|
188
|
+
## Hide in the UI, check on the server
|
|
189
|
+
|
|
190
|
+
The template checks every protected action three times, and no layer trusts the one above it:
|
|
191
|
+
|
|
192
|
+
```mermaid
|
|
193
|
+
flowchart LR
|
|
194
|
+
Page["Page<br/>holds hides the button"] --> Route["BFF route<br/>403 without the requirement"]
|
|
195
|
+
Route --> CI["CI<br/>grants, Max Privileges, policies<br/>for the run and each record"]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
An Access Requirement is a serializable guard built from `requires`, `enters`, `allOf` and `anyOf`. A feature package exports the requirement of each operation, so the page and the route check the same value. On the server, `CiRuntime.access(cookie)` returns the app's slice of the user's capabilities, and `holds(slice, requirement)` checks one requirement against it. The browser SDK session holds no access data.
|
|
199
|
+
|
|
200
|
+
```tsx
|
|
201
|
+
const CrmLeaf = async () => {
|
|
202
|
+
const access = await readSessionAccess()
|
|
203
|
+
return <CrmWorkspace canConvert={holds(access, convertLeadRequirement)} />
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The leaf reads request cookies, so it sits inside `<Suspense>`. Without a session, or when CI is down, the access slice is `null` and no gated control appears. When the user's access changes during a session, CI reports it on the realtime stream and `RealtimeProviders` refreshes the route, so the button appears or disappears without a reload.
|
|
208
|
+
|
|
209
|
+
Dashboard feature flags such as `organization_onboarding`, `knowledge_setup` and `apps_setup` belong to the hiding layer only. They remove Dashboard entry points and leave capabilities and server checks unchanged.
|
|
210
|
+
|
|
211
|
+
## Worked example: Sales members can convert leads
|
|
212
|
+
|
|
213
|
+
The template's CRM page has a Convert action that starts the convert-lead workflow. Here is how to give it to every Sales member.
|
|
214
|
+
|
|
215
|
+
1. Check what the template does today. `convertLeadRequirement` is `{ mode: "on", requires: "platform.workflows" }`. Only the Sales manager profile allows `core.platform.workflows`, so today only members of Sales managers see Convert and can run it. A member who is only in Sales gets no button, and the BFF route answers 403.
|
|
216
|
+
2. Add `allow(core.platform.workflows)` to `repProfile` in the organization package. The app's Max Privileges already allow `platform.workflows`, so they need no change. Bump `VERSION`, then build, publish, promote and install the package.
|
|
217
|
+
3. Check the Lead write. The browser call is delegated, so the workflow runs as the signed-in user and not as `convertLeadRunner`. The run marks the Lead `converted: true`, and the Lead write policy requires CRM `manage`, which reps do not hold. The template lets only managers convert, so it never exercises this path. If CI checks that write against the user's policies, a rep also needs CRM `manage`, or a narrower write policy with `writableFields: ["converted"]`. Confirm it with one trial run before the demo.
|
|
218
|
+
4. Sign in as a user who is only in Sales. The CRM page now shows Convert, and `POST /api/leads/:id/convert` answers `{ runId }`. Run `POST /admin/access/explain` to see which grant gives `platform.workflows`. Allow up to 60 seconds after a grant change, or wait for the realtime access event to refresh the page.
|
|
219
|
+
|
|
220
|
+
For a one-off demo you can skip the package change. An administrator grants the Sales manager profile to a single user in the Dashboard, which creates a runtime grant. The package stays the source of truth for the Sales tree, and the next demo starts from the declared grants again.
|
|
221
|
+
|
|
222
|
+
## Debug and test access
|
|
223
|
+
|
|
224
|
+
To answer "why can or can't this user do this?", call `POST /admin/access/explain`. The same check is the `explain_access` MCP tool and `ci.access.explain` in the server SDK. `GET /admin/access/members/:userId/access` lists a member's effective access with the grant behind each capability.
|
|
225
|
+
|
|
226
|
+
When a user installed the package and still cannot sign in to the app, check three things in order. The user must be in Sales or Sales managers, the grant for that Group must hold the app gate, and an administrator must have rotated the app's client secret. Install does none of this. A package that declares grants also needs an install with a user's management token, because a system install fails with `installer_required`.
|
|
227
|
+
|
|
228
|
+
You can test policies and profiles without a running CI. `accessTest` from `@collective-intelligence/extensions-sdk-backend` loads your packages and answers questions as a given user:
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
const check = accessTest([orgPackage, hrPackage], { corePolicies, entities })
|
|
232
|
+
|
|
233
|
+
check.as({ user, grants }).canRead(schema, record)
|
|
234
|
+
check.as({ user, grants }).holds(requirement)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The same object offers `.read(...)` for the masked record, `.canUpdate(...)` and `check.conditionTests()` for the built-in condition tests.
|
|
238
|
+
|
|
239
|
+
## Related pages
|
|
240
|
+
|
|
241
|
+
- [External apps](../develop/external-apps.md)
|
|
242
|
+
- [Knowledge](../data/knowledge.md)
|
|
243
|
+
- [Extensions](../develop/extensions.md)
|
|
244
|
+
- [The template](../template/index.md)
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Platform architecture
|
|
2
|
+
|
|
3
|
+
The parts of Collective Intelligence, the three integration models, and how a demo package moves from build to install.
|
|
4
|
+
|
|
5
|
+
A demo built on Collective Intelligence (CI) produces two artifacts and points both at a CI deployment that already runs. The first is an extension package that CI installs into an Organization. The second is a web app that runs on your own host and calls CI. Your team does not run the backend, its workers, Compute, Media, the Dashboard or Studio; the CI deployment provides all of them.
|
|
6
|
+
|
|
7
|
+
## Tenant and Organization
|
|
8
|
+
|
|
9
|
+
A tenant is one CI deployment and its top-level security boundary, so one installation of CI has exactly one tenant. An Organization is a data and access partition inside a tenant, and each Organization belongs to one tenant. For a demo, the customer is almost always an Organization inside an existing tenant. Do not use "tenant" as another word for the customer.
|
|
10
|
+
|
|
11
|
+
Platform-wide choices live at tenant scope: tenant users, oversight of Organizations, feature flags, AI model availability and defaults, maintenance and monitoring. Most of what a demo touches lives at Organization scope: users and Groups, installed packages, connector instances, Knowledge, tools, Skills, workflows and Studio apps.
|
|
12
|
+
|
|
13
|
+
CI never infers either scope. Code installed inside CI receives the tenant and Organization from CI on each call. An external application names the tenant URL in its configuration and the Organization in each data operation.
|
|
14
|
+
|
|
15
|
+
## Surfaces
|
|
16
|
+
|
|
17
|
+
| Surface | Who uses it | What it does for a demo |
|
|
18
|
+
| ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| Dashboard | Administrators | Configures the Organization: users, Groups, access, packages, connectors, Knowledge schemas, agents, Skills, tools, workflows, external applications and MCP. |
|
|
20
|
+
| Studio | End users | Desktop app where people chat with agents, open Studio apps, fill agent forms and read Documents. Each tenant has an install page with a Connect Studio button, so nobody types a backend URL. |
|
|
21
|
+
| Backend API | Dashboard, Studio, CLI, your app | Serves every HTTP route. Its OpenAPI document is the authority that the SDKs and the CLI are generated from. |
|
|
22
|
+
| Workers | The backend | Background workers run long jobs, and interactive workers run the agent and tool work that users wait for. |
|
|
23
|
+
| Compute | The backend | Runs transcription, transcoding and conversion from a queue. Each capability has its own slots, so a long transcode does not block transcription. |
|
|
24
|
+
| Media | Browsers | Serves file bytes and image transforms from URLs that the backend signs. No file byte passes through a backend endpoint. |
|
|
25
|
+
|
|
26
|
+
Your code never calls Compute. For files, the backend decides who can see each one and signs its URL, and Media only checks the signature. A principal can fetch a file if, and only if, it can see the item the file is attached to.
|
|
27
|
+
|
|
28
|
+
> **Note:** Some Dashboard areas, such as Organization onboarding, Knowledge setup and
|
|
29
|
+
> apps setup, start disabled. A tenant administrator turns them on per
|
|
30
|
+
> Organization with feature flags. If a demo Organization lacks a menu item,
|
|
31
|
+
> check the tenant feature flags first.
|
|
32
|
+
|
|
33
|
+
## Three ways to integrate
|
|
34
|
+
|
|
35
|
+
CI supports three integration models, and none of them depends on another.
|
|
36
|
+
|
|
37
|
+
```mermaid
|
|
38
|
+
flowchart LR
|
|
39
|
+
subgraph tenant["CI tenant (one deployment)"]
|
|
40
|
+
dashboard["Dashboard"]
|
|
41
|
+
studio["Studio"]
|
|
42
|
+
api["Backend API"]
|
|
43
|
+
workers["Workers"]
|
|
44
|
+
compute["Compute"]
|
|
45
|
+
media["Media"]
|
|
46
|
+
subgraph org["Organization"]
|
|
47
|
+
pkg["Installed extension package"]
|
|
48
|
+
end
|
|
49
|
+
dashboard --> api
|
|
50
|
+
studio --> api
|
|
51
|
+
api --> workers
|
|
52
|
+
api --> compute
|
|
53
|
+
api --- pkg
|
|
54
|
+
end
|
|
55
|
+
webapp["Your web app (BFF)"] -->|"Application API"| api
|
|
56
|
+
api -->|"signed calls"| gateway["Your Gateway"]
|
|
57
|
+
browser["Browser"] -->|"signed URLs"| media
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The first model installs code inside CI. An extension package declares schemas, Groups, access, agents, Skills, tools, workflows and Studio apps, and it can add React widgets to Studio and the Dashboard. CI runs this code in its own hosts and gives it the current tenant and Organization on each call. See [Extensions](../develop/extensions.md).
|
|
61
|
+
|
|
62
|
+
The second model is an external application: software your team hosts that calls CI over HTTP. The template's web app is one. A server-side BFF holds the app's confidential credentials, signs users in with their CI identity and calls the Application API. See [External apps](../develop/external-apps.md).
|
|
63
|
+
|
|
64
|
+
In the third model, CI calls your server. A Gateway, installed in your server with the server SDK, exposes your own resources, datasets and business operations to CI. Your application keeps its database, its business rules and its user sessions, and CI can import your resources into Knowledge, query your datasets and call your operations as tools.
|
|
65
|
+
|
|
66
|
+
Choose the direction by asking who owns the records. When CI owns them, as with the template's Leads that people edit from Studio and from the web app, call CI from your app. When your app's database stays the source of truth and CI must read or act on it, expose the data through a Gateway. The template uses only the outbound direction and needs no Gateway connection to run.
|
|
67
|
+
|
|
68
|
+
## Packages
|
|
69
|
+
|
|
70
|
+
A package in CI distributes platform capabilities, and code is only one part of it. One package can carry Knowledge domains and schemas, connectors, tools, Skills, agents, workflows, Studio apps and widgets, Groups, Access Profiles and external application registrations. A customer solution package usually holds the shared pieces for one Organization's initiative. One package per Organization is a convention, and CI does not enforce it.
|
|
71
|
+
|
|
72
|
+
CI's own built-in features ship as packages with the same manifest, bundle and runtime contracts, so a demo package uses the same mechanism as the platform's core packages.
|
|
73
|
+
|
|
74
|
+
Items that a package declares belong to the package installation. A Declared Studio App, for example, is read-only in the Studio builder and changes only when you deploy a new release of its package. Ordinary saves in the Dashboard never install or change packages.
|
|
75
|
+
|
|
76
|
+
### Package lifecycle
|
|
77
|
+
|
|
78
|
+
```mermaid
|
|
79
|
+
flowchart LR
|
|
80
|
+
declare["Declarations in TypeScript"] --> build["ci package build"]
|
|
81
|
+
build --> archive["Immutable archive and release manifest"]
|
|
82
|
+
archive --> validate["Validate"]
|
|
83
|
+
validate --> publish["Publish"]
|
|
84
|
+
publish --> promote["Promote"]
|
|
85
|
+
promote --> install["Install or update in one Organization"]
|
|
86
|
+
install --> desired["Desired release"]
|
|
87
|
+
desired -->|"prepared on every host"| serving["Serving release"]
|
|
88
|
+
desired -.->|"preparation fails"| previous["Previous release keeps serving"]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Each published version is an immutable release. Installing or updating a package in an Organization selects a desired release, and CI then prepares it on every host that needs it: the backend, the Dashboard and Studio. The serving release changes only when every host is ready. If preparation fails, the previous compatible release continues to serve. Backend code and React widgets from one release always move together and cannot drift to different versions.
|
|
92
|
+
|
|
93
|
+
Rollback selects an earlier release through the same lifecycle checks. It does not restore records, and it does not write inverse changes to definitions.
|
|
94
|
+
|
|
95
|
+
The CLI and the Dashboard reach the same backend operation for each package action. The CLI also has `ci deploy`, which publishes the release only when it is absent, promotes it only when needed, and then installs or updates it. Copying a package archive somewhere gives it no authority; only an installation makes a package active in an Organization.
|
|
96
|
+
|
|
97
|
+
## How the template maps onto CI
|
|
98
|
+
|
|
99
|
+
The `next-effect-app` template has two composition roots, one for each side of the boundary.
|
|
100
|
+
|
|
101
|
+
| Folder | Runs where | SDKs | Reaches CI by |
|
|
102
|
+
| ----------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------ |
|
|
103
|
+
| `apps/extensions` | Inside CI, installed in the Organization | `extensions-sdk`, `extensions-sdk-backend`, `extensions-sdk-frontend-react`, `ui-react` | `ci package build`, publish, promote and install |
|
|
104
|
+
| `apps/web` | Your host, as a Next.js app | `external-apps-server-sdk` on the server, `external-apps-client-sdk-react` in the browser | The BFF calls the Application API |
|
|
105
|
+
|
|
106
|
+
The package root in `apps/extensions` is short. It combines the declared components with the Lead score card widget for Studio:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
export default declarePackage({
|
|
110
|
+
components: packageComponents,
|
|
111
|
+
hostedContributions: [
|
|
112
|
+
declareFrontendCatalogContribution({
|
|
113
|
+
compatibility: { react: "^19.0.0" },
|
|
114
|
+
fqn: leadScoreCardContributionFqn,
|
|
115
|
+
host: "studio",
|
|
116
|
+
load: async () => await import("./studio")
|
|
117
|
+
})
|
|
118
|
+
],
|
|
119
|
+
manifest: packageManifest
|
|
120
|
+
})
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
When installed, that package creates the CRM domain with the Lead and Opportunity schemas, the Sales Groups and their access, the app registration, the convert-lead workflow, the lead qualifier agent, the Sales desk Studio app and the widget. The web app has no database of its own. Users sign in with their CI identity, Leads and Opportunities live in CI Knowledge, and lead conversion runs as a CI workflow.
|
|
124
|
+
|
|
125
|
+
> **Warning:** The web app serves two route families that start with `/api`. The `/api/app/*`
|
|
126
|
+
> routes are the app's own HTTP API, merged from its packages. The `/api/*`
|
|
127
|
+
> routes are the BFF that forwards to CI. The browser calls only these
|
|
128
|
+
> same-origin routes and never holds the client secret.
|
|
129
|
+
|
|
130
|
+
The Overview and Lead intake pages of the template work with no CI at all, because intake data stays in memory. Only the CRM pages need a connected tenant.
|
|
131
|
+
|
|
132
|
+
## Where data lives
|
|
133
|
+
|
|
134
|
+
Knowledge holds durable business concepts such as customers, leads and assets as records that follow declared schemas, and it is what agents, Skills, workflows and Studio apps query. Datasets hold typed, high-volume records such as financial measures or sensor readings, which Knowledge does not fit. Documents are a separate surface for files and Document Collections, with their own page in Studio. Read [Knowledge](../data/knowledge.md), [Datasets](../data/datasets.md) and [Connectors](../data/connectors.md) for the details.
|
|
135
|
+
|
|
136
|
+
## Next pages
|
|
137
|
+
|
|
138
|
+
- [Entrypoints](entrypoints.md): How people, apps and agents reach CI, and what your code imports.
|
|
139
|
+
- [Access](access.md): Access Profiles, Access Grants and Max Privileges.
|
|
140
|
+
- [Extensions](../develop/extensions.md): Write the package that CI installs.
|
|
141
|
+
- [External apps](../develop/external-apps.md): Build the web app that calls CI.
|
|
142
|
+
- [Template](../template/index.md): Start from the `next-effect-app` template.
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
# Entrypoints
|
|
2
|
+
|
|
3
|
+
The ways people, apps and agents enter CI at runtime, and the package subpaths that demo code imports.
|
|
4
|
+
|
|
5
|
+
In this guide, "entrypoint" has two meanings. Runtime entrypoints are the ways people, apps and agents enter CI: the Dashboard, Studio, the CLI, the HTTP API, MCP, workflow triggers and Realtime. Code entrypoints are the package subpaths that demo code imports, both from the CI SDKs and from the template's own packages.
|
|
6
|
+
|
|
7
|
+
## Runtime entrypoints
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart LR
|
|
11
|
+
admin["Administrator"] --> dashboard["Dashboard"]
|
|
12
|
+
user["End user"] --> studio["Studio"]
|
|
13
|
+
dev["Developer or pipeline"] --> cli["ci CLI"]
|
|
14
|
+
script["Script with an API key"] --> http["HTTP API"]
|
|
15
|
+
browser["Your browser code"] --> bff["Your BFF"]
|
|
16
|
+
bff --> appapi["Application API"]
|
|
17
|
+
ai["AI client"] --> mcp["MCP endpoint"]
|
|
18
|
+
system["External system"] --> trigger["Workflow trigger"]
|
|
19
|
+
clock["Schedule"] --> trigger
|
|
20
|
+
subgraph ci["CI"]
|
|
21
|
+
dashboard
|
|
22
|
+
studio
|
|
23
|
+
http
|
|
24
|
+
appapi
|
|
25
|
+
mcp
|
|
26
|
+
trigger
|
|
27
|
+
realtime["Realtime events"]
|
|
28
|
+
end
|
|
29
|
+
cli --> http
|
|
30
|
+
realtime -->|"ids of changed records"| browser
|
|
31
|
+
http -->|"signed calls"| gateway["Your Gateway"]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Entrypoint | Who uses it | Authenticates with | Typical demo use |
|
|
35
|
+
| --------------------- | ---------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
36
|
+
| Dashboard | Administrators | Organization sign-in, including SSO | Install the package, add users to Groups, manage access, rotate an app secret |
|
|
37
|
+
| Studio | End users | CI sign-in through the tenant's Connect Studio link | Chat with agents, open a Studio app, use a widget |
|
|
38
|
+
| CLI (`ci`) | Developers and pipelines | CLI Session from `ci login`, or `CI_MANAGEMENT_TOKEN` | Build and deploy the package, create API keys |
|
|
39
|
+
| HTTP API | Scripts and unattended runs | API key of a service principal, limited by Max Privileges | Script demo setup, run agent conversations without a person |
|
|
40
|
+
| External applications | Your web app's server | OAuth client credentials, member tokens, server credentials | The template's CRM pages and lead conversion |
|
|
41
|
+
| MCP | AI clients and assistants | Bearer session token or API key | Let an assistant run Skills and workflows |
|
|
42
|
+
| Workflow triggers | Other systems, the clock, apps, record changes | Depends on the trigger; the webhook trigger uses an API key | Start a workflow from a webhook or on a schedule |
|
|
43
|
+
| Realtime | Your browser, through your BFF | Single-use ticket that your server requests | Refresh lists when a record changes |
|
|
44
|
+
|
|
45
|
+
### Dashboard and Studio
|
|
46
|
+
|
|
47
|
+
Administrators configure an Organization in the Dashboard. Its Organization admin area holds accounts, Groups, Access Profiles, capabilities, Max Privileges, access explanations, packages and a Developers area; separate areas hold AI (agents, Skills, tools, workflows, approvals), Apps (Studio, external applications, MCP), datasets and Documents. The Developers area has tabs for the CLI, connections, service principals and variables, and its CLI tab shows the exact `ci login` command for the Organization.
|
|
48
|
+
|
|
49
|
+
End users work in Studio. They chat with agents, open Studio apps, fill agent forms and read Documents. A package can ship a whole Studio app, which CI creates and publishes on install; the template's Sales desk is one. A Studio widget never holds CI credentials. It calls CI through the Studio API client from `@collective-intelligence/extensions-sdk-frontend-react/studio-api`, which Studio binds to its own signed-in transport, so each request runs with the current user's permissions.
|
|
50
|
+
|
|
51
|
+
### CLI
|
|
52
|
+
|
|
53
|
+
The `ci` CLI runs on Bun and calls the backend only through its generated OpenAPI operations. Install it globally and sign in against the API URL of your tenant:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm install -g @collective-intelligence/cli
|
|
57
|
+
ci login <api-url> --organization <organization-id>
|
|
58
|
+
ci whoami
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`ci login` asks you to approve the device in the Dashboard and stores a 30-day CLI Session in your user profile. `ci upgrade` updates a global install.
|
|
62
|
+
|
|
63
|
+
> **Note:** `ci login` needs the API URL. It reads the tenant's discovery document at
|
|
64
|
+
> `/.well-known/ci-configuration` and rejects a Dashboard URL as "not a CI API
|
|
65
|
+
> URL".
|
|
66
|
+
|
|
67
|
+
The CLI takes credentials from a flag first, then from the environment (`CI_BACKEND_URL`, `CI_MANAGEMENT_TOKEN`), then from the stored profile. Developers at a terminal use `ci login`, and pipelines set `CI_MANAGEMENT_TOKEN`. Publishing reads `CI_PUBLISHER_TOKEN` from the environment only.
|
|
68
|
+
|
|
69
|
+
For a package, a demo uses `ci package build`, `validate`, `publish`, `promote` and `install`, or the single `ci deploy` command, which publishes only when the release is absent, promotes only when needed, and then installs or updates. `ci package dev` runs a development session that serves your package modules from your machine to real Dashboard and Studio hosts. `ci package codegen` generates TypeScript types from the package schemas, and `ci doctor` checks discovery, signing keys, Organization access and redirect URIs.
|
|
70
|
+
|
|
71
|
+
### HTTP API and API keys
|
|
72
|
+
|
|
73
|
+
The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas are the authority, and the SDKs and the CLI are generated from them. A demo meets these public route families:
|
|
74
|
+
|
|
75
|
+
- `/application/v1/*`, the Application API for external applications
|
|
76
|
+
- `/oauth/*`, the authorization server for app sign-in
|
|
77
|
+
- `/.well-known/ci-configuration`, the tenant discovery document
|
|
78
|
+
- `/mcp`, the MCP endpoint
|
|
79
|
+
- `/openapi.json`, the API description
|
|
80
|
+
|
|
81
|
+
Other route families serve the Dashboard and Studio. A generated operation is not safe for a client just because it exists in the OpenAPI document.
|
|
82
|
+
|
|
83
|
+
Each credential is a separate authority:
|
|
84
|
+
|
|
85
|
+
| Credential | Held by | Used for |
|
|
86
|
+
| ------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
|
|
87
|
+
| CLI Session | A person | Interactive CLI work for 30 days, from device approval |
|
|
88
|
+
| Management token (`CI_MANAGEMENT_TOKEN`) | A pipeline | CLI work with an Organization API key or a session token |
|
|
89
|
+
| Publisher credential (`CI_PUBLISHER_TOKEN`) | A release pipeline | Publish and promote for one package only |
|
|
90
|
+
| Client id and client secret | An external application | OAuth sign-in; only a confidential app has a secret |
|
|
91
|
+
| Server credential | An external application's server | Calls that act with the app's own grants |
|
|
92
|
+
| API key | A service principal | Calls that act with the principal's grants, limited by a Max Privileges template |
|
|
93
|
+
|
|
94
|
+
API keys have no scopes. A key never acts beyond its Max Privileges template, and creating, rotating or revoking a key needs manage access to API keys, which no API key has:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
ci apps credentials upsert <app-fqn-or-id> --name pipeline --env-file .env.server
|
|
98
|
+
ci api-keys upsert --principal <principal-fqn> --name pipeline \
|
|
99
|
+
--max-privileges <template-fqn> --env-file .env.pipeline
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
A service principal key can run Studio agent conversations without a person. It can list apps, open and read conversations, send agent turns, and cancel or close a conversation. Approvals, memory, preferences and answers to questions stay with people.
|
|
103
|
+
|
|
104
|
+
> **Warning:** A service principal run asks no questions and has no Studio memory. When a
|
|
105
|
+
> tool binding has an approval gate, the unattended run approves by default and
|
|
106
|
+
> records the approval without an actor. Plan scripted demos around that
|
|
107
|
+
> behavior.
|
|
108
|
+
|
|
109
|
+
### External applications
|
|
110
|
+
|
|
111
|
+
An external application signs users in with the OAuth authorization code flow and S256 PKCE, through `/oauth/authorize` and `/oauth/token`. The Dashboard shows the sign-in and consent page with the Organization's branding and login methods, including SSO. CI publishes OAuth 2.0 authorization server metadata and is not an OpenID Connect provider.
|
|
112
|
+
|
|
113
|
+
A public client runs only in the browser and has a client id without a secret. A confidential client is a backend that keeps a client secret. Access tokens last 300 seconds, and only a confidential app can renew one without a browser redirect or exchange a member session for a token. The template's app is confidential. Because its package declares the app, you take the client id from the Dashboard and rotate the secret there to get the client secret.
|
|
114
|
+
|
|
115
|
+
In the template, the browser calls only same-origin `/api/*` routes. The BFF behind them, built with `createExternalApplicationBffNextHandlers` from the server SDK, signs users in with a sealed cookie, forwards Resource calls per entity contract, requests Realtime tickets and forwards capabilities. Only `NEXT_PUBLIC_APPLICATION_ID` is visible to the browser.
|
|
116
|
+
|
|
117
|
+
An app can start only a workflow whose active External application trigger names that app. The template's `POST /api/leads/{id}/convert` route uses `createFixedWorkflowRoute`, which starts exactly one workflow that the server configures (`acme.app.workflows.convert-lead`) with the idempotency key `convert-lead:{leadId}`. The route rejects a workflow name or key in browser input. A call on behalf of a user runs as that user; a service call runs as the service principal that the workflow selects.
|
|
118
|
+
|
|
119
|
+
### MCP
|
|
120
|
+
|
|
121
|
+
The backend serves MCP at `/mcp` and at `/mcp/o/<organizationId>`. Every MCP request needs a valid Bearer session token or API key, including `initialize` and `tools/list`. The server exposes these tools: `list_memberships`, `list_skills`, `run_skill`, `get_skill_run`, `list_operations`, `invoke_operation`, `get_operation`, `cancel_operation` and `explain_access`. `run_skill` runs in the background, so a client polls `get_skill_run` for the result.
|
|
122
|
+
|
|
123
|
+
A workflow becomes visible to MCP clients through an MCP operation trigger. The caller gets an opaque handle and reads the result with `get_operation`. An MCP Profile, managed in the Dashboard under Apps > MCP, defines what an MCP principal can see and do, and it denies everything by default. The built-in Studio user profile grants Studio and MCP use.
|
|
124
|
+
|
|
125
|
+
### Workflow triggers
|
|
126
|
+
|
|
127
|
+
A trigger is the entrypoint of a workflow. The core workflows package ships these triggers:
|
|
128
|
+
|
|
129
|
+
| Trigger | Starts a run when |
|
|
130
|
+
| -------------------- | ------------------------------------------------- |
|
|
131
|
+
| On demand | A user starts the workflow explicitly |
|
|
132
|
+
| Schedule | A cron expression fires |
|
|
133
|
+
| Webhook | Another system sends an authenticated HTTP `POST` |
|
|
134
|
+
| External application | A bound external application starts it |
|
|
135
|
+
| MCP operation | An MCP client invokes it |
|
|
136
|
+
| Entity created | A Knowledge record is created |
|
|
137
|
+
| Entity updated | A Knowledge record changes |
|
|
138
|
+
| Entity deleted | A Knowledge record is deleted |
|
|
139
|
+
|
|
140
|
+
Integration packages add message and file triggers for Slack, Microsoft 365 email, Teams and Drive, Telegram, WhatsApp, Twilio SMS and WhatsApp, and Notion.
|
|
141
|
+
|
|
142
|
+
A webhook trigger authenticates the caller with an API key, accepts `POST`, and returns JSON. The caller waits for the workflow's response until a deadline and then receives `202` with the run id. CI binds event triggers when it publishes the workflow, and it refuses to publish an enabled trigger with an invalid activation declaration. In the template, the convert-lead workflow is declared in the package, and its trigger names the app's FQN, which install resolves to the app id.
|
|
143
|
+
|
|
144
|
+
### Realtime
|
|
145
|
+
|
|
146
|
+
Realtime tells open pages that records changed. Your server requests a single-use ticket from `POST /application/v1/realtime/tickets`, and the browser opens an event stream at `GET /application/v1/realtime/events` with that ticket. Events carry ids only, so the page reloads the records through its own data routes. A subscription names a schema and an optional field-equals filter:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
const realtime = createRealtimeClient({
|
|
150
|
+
ticketUrl: "/api/realtime/ticket",
|
|
151
|
+
document,
|
|
152
|
+
window,
|
|
153
|
+
onReset: () => queryClient.invalidateQueries(),
|
|
154
|
+
onAccessChanged: () => session.refresh()
|
|
155
|
+
})
|
|
156
|
+
realtime.subscribe(
|
|
157
|
+
{ schema: "crm.lead", filter: { field: "ownerId", eq: userId } },
|
|
158
|
+
(changes) => invalidateLeads(changes.map((change) => change.id))
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
On a reset, the client drops its local view and refetches every query that a subscription feeds.
|
|
163
|
+
|
|
164
|
+
### When CI calls you
|
|
165
|
+
|
|
166
|
+
A Gateway reverses the direction. You register a Gateway connection with an HTTPS endpoint and a setup credential, and after enrollment CI calls your server with short-lived ES256 tokens and a replay check. Your operations then become CI tools for chat, Skills and workflows. [External apps](../develop/external-apps.md) covers the setup.
|
|
167
|
+
|
|
168
|
+
## Code entrypoints
|
|
169
|
+
|
|
170
|
+
Demo code imports CI packages and its own workspaces by package name and exported subpath, for example `@acme/lead/views`, and never by relative path. Each subpath has one folder under `src/` with one `index.ts` and one `exports` entry in `package.json`.
|
|
171
|
+
|
|
172
|
+
### SDK subpaths
|
|
173
|
+
|
|
174
|
+
The SDKs split by where the code runs. [SDKs](../develop/sdks.md) has the full map; these are the subpaths a demo meets most.
|
|
175
|
+
|
|
176
|
+
| Package | Runs | Holds | Main subpaths |
|
|
177
|
+
| --------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
|
|
178
|
+
| `@collective-intelligence/extensions-sdk` | Inside CI | Declarations such as `declarePackage`, `declareAgent`, `declareWorkflow` | `.`, `./effect` |
|
|
179
|
+
| `@collective-intelligence/extensions-sdk-backend` | Inside CI | Contracts for backend tools and connectors | `.`, `./effect` |
|
|
180
|
+
| `@collective-intelligence/extensions-sdk-frontend` | Inside CI | Framework-neutral frontend catalog | `.`, `./effect` |
|
|
181
|
+
| `@collective-intelligence/extensions-sdk-frontend-react` | Inside CI | React bindings for Studio and Dashboard contributions | `./studio`, `./dashboard`, `./studio-api`, `./effect` |
|
|
182
|
+
| `@collective-intelligence/external-apps-server-sdk` | Your server | Server client, BFF, authentication, Gateway | `.`, `./auth/federated`, `./effect`, `./next`, `./gateway` |
|
|
183
|
+
| `@collective-intelligence/external-apps-client-sdk` | Your browser | React-free client and Realtime | `.`, `./resources`, `./effect` |
|
|
184
|
+
| `@collective-intelligence/external-apps-client-sdk-react` | Your browser | React hooks, including the entity hooks in `./resources` | `.`, `./resources`, `./effect` |
|
|
185
|
+
|
|
186
|
+
Every SDK puts its Promise API at the root and its Effect services, Layers, errors and Schemas at `/effect`. `effect` is a required peer of every SDK, so install it next to the SDK and keep one `effect` version in the app. Optional peers such as Next.js, Express, Drizzle, Better Auth and the AI SDK sit behind their own subpaths, so importing the server SDK root never loads them. In the template, `/next` is imported only inside `apps/web/src/server`, because `/next` loads Next.js and `/effect` does not.
|
|
187
|
+
|
|
188
|
+
### Template package subpaths
|
|
189
|
+
|
|
190
|
+
Each template package exposes up to six subpaths, and each subpath holds one kind of code:
|
|
191
|
+
|
|
192
|
+
| Subpath | Holds | Imported by |
|
|
193
|
+
| ---------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
|
|
194
|
+
| `domain` | Effect Schema models, resource contracts, schema FQNs, pure rules | Every other subpath and other packages |
|
|
195
|
+
| `ci` | CI declarations, written as factories over Organization handles | `@acme/organization` |
|
|
196
|
+
| `api` | The package `HttpApi` under `/api/app`, its groups and tagged errors | `server`, `headless`, app API composition |
|
|
197
|
+
| `server` | The route Layer of the package `HttpApi` and its services | `apps/web/src/server` only |
|
|
198
|
+
| `headless` | Typed client, query options, XState machines, entity bindings, Realtime hooks, simulated sources | `views`, the app |
|
|
199
|
+
| `views` | Wired React views on `@acme/ui`, with slots for feature parts | The app |
|
|
200
|
+
|
|
201
|
+
Imports point one way. `domain` imports no other subpath, `ci` imports neither `headless` nor `views`, and `headless` and `views` never import `server`. The `ci-solution/subpath-imports` lint rule enforces these rules.
|
|
202
|
+
|
|
203
|
+
A package exposes only the subpaths it needs. `@acme/lead` has all six, while `@acme/lead-qualification` has only `./ci`, which holds the lead qualifier agent, its Skill, its tool and its Studio widget. The `ci` subpath is where solution code becomes code that CI installs.
|
|
204
|
+
|
|
205
|
+
### Template routes and widgets
|
|
206
|
+
|
|
207
|
+
The web app has three route files, and each only re-exports handlers from `server/` and the packages:
|
|
208
|
+
|
|
209
|
+
| Route file | Serves |
|
|
210
|
+
| ------------------------------------- | ------------------------------------------------------- |
|
|
211
|
+
| `app/api/app/[[...path]]/route.ts` | The app's own API, composed from the package `HttpApi`s |
|
|
212
|
+
| `app/api/[...path]/route.ts` | The CI BFF: sign-in, Resources, Realtime ticket |
|
|
213
|
+
| `app/api/leads/[id]/convert/route.ts` | The fixed convert-lead workflow |
|
|
214
|
+
|
|
215
|
+
Inside CI, a Studio or Dashboard widget enters through a hosted contribution. You write `declareFrontendCatalogContribution({ fqn, host: "studio", load: () => import("./studio") })` and pass it to `declarePackage({ hostedContributions })`. The `load` function stays out of the serialized package manifest, and the loaded module exports `loadFrontendCatalog` for the host.
|
|
216
|
+
|
|
217
|
+
## Pick an entrypoint
|
|
218
|
+
|
|
219
|
+
| I want to | Use |
|
|
220
|
+
| ------------------------------------ | ---------------------------------------------------------- |
|
|
221
|
+
| Let users chat with an agent | Studio |
|
|
222
|
+
| Let users work in my web app | The Application API through my BFF |
|
|
223
|
+
| Start a workflow from my app | A fixed workflow route and an External application trigger |
|
|
224
|
+
| Start a workflow from another system | A webhook trigger |
|
|
225
|
+
| Run a workflow every night | A schedule trigger |
|
|
226
|
+
| Let an AI assistant call CI | MCP |
|
|
227
|
+
| Script a demo setup | The CLI with a service principal API key |
|
|
228
|
+
| Let CI call my system | A Gateway |
|
|
229
|
+
|
|
230
|
+
## Related pages
|
|
231
|
+
|
|
232
|
+
- [Platform architecture](architecture.md): Tenants, Organizations, surfaces and the package lifecycle.
|
|
233
|
+
- [Access](access.md): Access Profiles, Access Grants and Max Privileges.
|
|
234
|
+
- [SDKs](../develop/sdks.md): Every CI package and its subpaths.
|
|
235
|
+
- [External apps](../develop/external-apps.md): The BFF, sign-in and the Gateway.
|
|
236
|
+
- [Template](../template/index.md): The packages and routes of the template.
|