@collective-intelligence/extensions-sdk-backend 0.3.2 → 0.3.3
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/docs/guide/ai/index.md +36 -17
- package/docs/guide/ai/studio.md +245 -0
- package/docs/guide/data/connectors.md +81 -18
- package/docs/guide/data/datasets.md +6 -17
- package/docs/guide/data/documents.md +235 -0
- package/docs/guide/data/index.md +62 -0
- package/docs/guide/data/knowledge.md +21 -18
- package/docs/guide/develop/extensions.md +15 -14
- package/docs/guide/develop/external-apps.md +48 -14
- package/docs/guide/develop/infrastructure.md +135 -0
- package/docs/guide/develop/sdks.md +2 -2
- package/docs/guide/index.md +11 -7
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +125 -48
- package/docs/guide/scenarios/index.md +69 -46
- package/docs/guide/template/index.md +22 -9
- package/docs/guide/template/state-machines.md +1 -1
- package/package.json +3 -3
|
@@ -18,6 +18,26 @@ You need one when the demo has its own UI outside Studio and the Dashboard, or w
|
|
|
18
18
|
| CI reaching your data or actions | A Gateway |
|
|
19
19
|
| Your own logic with your own store | The app API under `/api/app` |
|
|
20
20
|
|
|
21
|
+
## Put it in the app or in CI
|
|
22
|
+
|
|
23
|
+
Before you write a screen, decide where each piece of its data and logic lives. [Platform architecture](../platform/architecture.md) gives the first question: who owns the records. The same question also places rules, access decisions and UI state:
|
|
24
|
+
|
|
25
|
+
| Question | Put it in CI | Keep it in the external app |
|
|
26
|
+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
27
|
+
| Do people in Studio, agents or workflows use these records? | A [Knowledge](../data/knowledge.md) schema. The app reads and writes the records through the BFF. | |
|
|
28
|
+
| Does the customer's database stay the source of truth? | Only what CI must read or act on, exposed through a Gateway | The records, in the app's database |
|
|
29
|
+
| Must agents, workflows and the app apply one business rule the same way? | A tool or a workflow in the package. The app starts it and does not write the rule again. | A rule that already runs in the customer's backend, exposed as a Gateway operation |
|
|
30
|
+
| Who may see or change a record? | Capabilities, Knowledge data policies and Access Grants | Only the choice to hide a control |
|
|
31
|
+
| Is it UI state, such as form steps, filters and drafts, or app-only data? | | State machines, query state and the app API store |
|
|
32
|
+
|
|
33
|
+
Records go to Knowledge when more than the app uses them. In the template, the Sales desk Studio app lists Leads and the lead qualifier agent reads them, so Leads live in Knowledge and the web app keeps no Lead table of its own. The template's lead score is a tool that the agent and a Skill call, and the convert-lead workflow is a package declaration that the app only starts through a [Fixed workflow route](external-apps.md#reads-and-writes-through-the-sdk).
|
|
34
|
+
|
|
35
|
+
Access stays in CI even when the app shows the screen. The BFF checks an Access Requirement before it calls CI, and CI then checks each record again. A page can use the same requirement to hide a button, but the server check makes the decision.
|
|
36
|
+
|
|
37
|
+
Data that no CI user, Studio page or agent reads stays in the app. The template's intake form keeps its requests in an in-memory store behind the app API, and you replace that store with a database. When the customer's database must stay the source of truth, the records stay there too. A Gateway then exposes only what CI needs: remote resources that an Organization admin maps onto a Knowledge schema through a [connector](../data/connectors.md), dataset queries, and business operations that agents call as tools. When agents need only a few fields, keep personal data in the app and put only the needed fields into Knowledge.
|
|
38
|
+
|
|
39
|
+
Secrets stay on the app's server. The browser gets no CI token and no client secret, and in the template `NEXT_PUBLIC_APPLICATION_ID` is the only value it sees. The sign-in secret, the session secrets and the Server Credential live in the server's environment. Deploy and management tokens never reach the web app. A secret that code inside CI needs, such as an API key for a third-party service, is a `secret` package variable that a Tenant admin sets in the Organization variables after deploy, as [Extensions](extensions.md) describes. An Organization admin can read the variables but cannot change them.
|
|
40
|
+
|
|
21
41
|
## Declare the app
|
|
22
42
|
|
|
23
43
|
A package declares the app as an OAuth client with `declareExternalApplication`. The template's declaration, with a placeholder origin:
|
|
@@ -40,19 +60,33 @@ export const acmeApplication = declareExternalApplication({
|
|
|
40
60
|
|
|
41
61
|
The declaration has no `scopes` field. What a user may do through the app comes from grants that hold the app gate and from the Max Privileges declared for the app's user tokens, both described on [Grants and permissions](../platform/access.md).
|
|
42
62
|
|
|
43
|
-
|
|
63
|
+
The CLI writes the app's connection values into an env file: `CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`, `CI_ORGANIZATION_ID`, `CI_JWKS_URL` and, when a secret is known, `CI_CLIENT_SECRET`. Server code reads them with `readApplicationEnrollment(process.env)` and never names them one by one. Two commands write these values, and the right one depends on who created the app:
|
|
64
|
+
|
|
65
|
+
| The app was created by | Command | Client secret |
|
|
66
|
+
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
|
|
67
|
+
| A package, as the template | `ci apps env <application> --env-file <path>` | Left out; issue one with `ci apps rotate-secret <application-id>` |
|
|
68
|
+
| The CLI | `ci apps enroll --fqn <fqn> --redirect-uri <url> ...` | Written by the first confidential create or by `--rotate-secret` |
|
|
69
|
+
|
|
70
|
+
`ci apps env` accepts an Application Id or an FQN and changes nothing in CI. `ci apps enroll` creates or replaces an app by FQN, so it refuses an app that a package declared. The Application Id is the registration id (the `app_id` claim), and the Client Id is the OAuth `client_id`. They are different values, and every CLI output names both.
|
|
44
71
|
|
|
45
72
|
Next to the enrollment, the template reads `APP_ORIGIN` (the public HTTPS origin), `CI_TENANT_URL`, `SESSION_SECRETS` (comma-separated, current secret first, so you can rotate) and `NEXT_PUBLIC_APPLICATION_ID`, the only value the browser sees.
|
|
46
73
|
|
|
47
74
|
## After install
|
|
48
75
|
|
|
49
|
-
Installing the package registers the app. Users can sign in and see data only after the first
|
|
76
|
+
Installing the package registers the app as a confidential client with no secret. Users can sign in and see data only after the first five steps below; the sixth gives refused users a readable page. Run the CLI steps as an Organization admin, signed in with `ci login <api-url> --organization <organization-id>`.
|
|
77
|
+
|
|
78
|
+
1. Write the connection values with `ci apps env <application> --env-file apps/web/.env.local`. The command leaves out the client secret and prints the Application Id that the next step needs.
|
|
79
|
+
2. Rotate the sign-in secret with `ci apps rotate-secret <application-id>`, or with "Rotate secret" on the Dashboard External Apps page. CI shows the secret once, so store it as `CI_CLIENT_SECRET` at once. Each rotation ends the previous secret. Run `ci apps env` first: when the env file holds a secret for a different Client Id, `ci apps env` refuses to write the file.
|
|
80
|
+
3. Create a Server Credential for the app's server with `ci apps credentials upsert <application> --name <name> --env-file <server-env-file>`. Use a separate env file, because this file also stores its secret as `CI_CLIENT_SECRET`.
|
|
81
|
+
4. Add users to the Group whose grant holds the app gate. In the template that is Sales or Sales managers. The package declares the Groups and leaves them empty.
|
|
82
|
+
5. Give the app server read access to Leads. The template's Read Port reads with the server's own credential, and the package declares no grant for it.
|
|
83
|
+
6. Set `errorPath` on the federated auth so that a refused sign-in lands on a page instead of a JSON answer. The callback reports `access_denied`, `authorization_failed`, `invalid_state`, `invalid_request`, `invalid_identity` or `user_auth_unavailable`.
|
|
84
|
+
|
|
85
|
+
The app holds two different secrets. The sign-in secret from step 2 belongs to the OAuth client and only signs users in. The Server Credential from step 3, whose secret starts with `dsc_`, authenticates the server's own calls in service mode and acts with the Access Grants given to the app's server. CI refuses the sign-in secret on a server call, so a server that reads without a user needs the Server Credential.
|
|
50
86
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
4. Give the app server read access to Leads. The template's Read Port reads with the app's own credential, and the package declares no grant for it.
|
|
55
|
-
5. Set `errorPath` on the federated auth so that a refused sign-in lands on a page instead of a JSON answer. The callback reports `access_denied`, `authorization_failed`, `invalid_state`, `invalid_request`, `invalid_identity` or `user_auth_unavailable`.
|
|
87
|
+
> **Warning:** `ci apps enroll`, `ci apps redirect-uris` and `ci apps origins` refuse an app
|
|
88
|
+
> that a package declared. Change its redirect URIs and origins in
|
|
89
|
+
> `declareExternalApplication` and deploy a new package release.
|
|
56
90
|
|
|
57
91
|
## Sessions
|
|
58
92
|
|
|
@@ -74,7 +108,7 @@ const auth = createFederatedAuth({
|
|
|
74
108
|
})
|
|
75
109
|
```
|
|
76
110
|
|
|
77
|
-
`createFederatedAuth` handles the PKCE login, the callback, session reads and logout under `/api/auth`. Register `<origin>/api/auth/callback` with `ci apps redirect-uris add` and
|
|
111
|
+
`createFederatedAuth` handles the PKCE login, the callback, session reads and logout under `/api/auth`. Register `<origin>/api/auth/callback` as a redirect URI and the origin as an allowed origin. A package-declared app lists both in its declaration; an app created with the CLI adds them with `ci apps redirect-uris add` and `ci apps origins add`. The session cookie is `__Host-ci-federated` with `Secure`, `HttpOnly` and `SameSite=Lax`, which is why `APP_ORIGIN` must use HTTPS. On a laptop without a TLS proxy, `allowLoopbackHttp: true` lets `http://localhost:3000` work with a cookie named `ci-federated` and no `Secure` flag. Keep that option off in production.
|
|
78
112
|
|
|
79
113
|
Access tokens always live 300 seconds. A confidential client that passes its `clientSecret` to `createFederatedAuth` renews them silently: when a token has 30 seconds or less left, the session lookup gets a new one first. The renewed token stays in process memory and the cookie is written once at sign-in, so a server restart only triggers another renewal. The session itself lasts `sessionTtlSeconds`, 86400 by default and at most 604800, and never longer than the user's CI session.
|
|
80
114
|
|
|
@@ -137,7 +171,7 @@ The template mounts three route files:
|
|
|
137
171
|
| `app/api/leads/[id]/convert/route.ts` | Convert a Lead through a Fixed workflow route |
|
|
138
172
|
| `app/api/app/[[...path]]/route.ts` | The app's own Effect `HttpApi`, with OpenAPI at `/api/app/openapi.json` |
|
|
139
173
|
|
|
140
|
-
A server call to CI uses one of three identities. A delegated call, the default, uses the signed-in user's token, and the template's convert route works this way. `runAsApplication` switches one call to the app's confidential credentials and needs an audit subject. A service-mode client (`createServerClient({ authentication: { mode: "service", credentials } })`) always uses the app's
|
|
174
|
+
A server call to CI uses one of three identities. A delegated call, the default, uses the signed-in user's token, and the template's convert route works this way. `runAsApplication` switches one call to the app's confidential credentials and needs an audit subject. A service-mode client (`createServerClient({ authentication: { mode: "service", credentials } })`) always uses the app's Server Credential and gets the same answer for every user, which is what the template's Read Port does.
|
|
141
175
|
|
|
142
176
|
## Reads and writes through the SDK
|
|
143
177
|
|
|
@@ -159,7 +193,7 @@ const handle = createFixedWorkflowRoute<{ leadId: string }, { leadId: string }>(
|
|
|
159
193
|
|
|
160
194
|
The route rejects any `workflowId` or `workflowFqn` in the browser input, checks the Access Requirement, stamps `x-organization-id` from the session and returns `{ runId }`. The template's tests prove each refusal: an injected `workflowId` gets 400, no session gets 401, a missing capability gets 403, and two clicks reuse the idempotency key `convert-lead:<id>`.
|
|
161
195
|
|
|
162
|
-
The workflow must have an External application trigger bound to the app and an audience that includes it (`audience: { applications: [application] }`). A delegated call runs the workflow as the signed-in user. A service
|
|
196
|
+
The workflow must have an External application trigger bound to the app and an audience that includes it (`audience: { applications: [application] }`). A run acts as the identity that started it. A delegated call runs the workflow as the signed-in user. A call in service mode or with `runAsApplication` has no person, so the run uses the workflow's run-as service principal. CI publishes a triggered workflow only when it names one, which is why the template ships `convertLeadRunner`.
|
|
163
197
|
|
|
164
198
|
A run returns its `runId` at once. The template's `convertLeadTask` posts the convert route, follows the run with `runs.follow({ runId })` until it ends (10 minutes by default), and then invalidates the entity reads so every view reloads.
|
|
165
199
|
|
|
@@ -182,7 +216,7 @@ Tags cover all CI reads, a schema, a list, one entity and one Realtime topic. A
|
|
|
182
216
|
```mermaid
|
|
183
217
|
flowchart LR
|
|
184
218
|
W1[Write through the BFF] --> N[nextInvalidate]
|
|
185
|
-
W2[
|
|
219
|
+
W2[Write outside the BFF] --> RT[Realtime change in an open tab] --> RV[Revalidate route]
|
|
186
220
|
W3[Effect server write] --> L[CacheInvalidation.layerNext on the fiber]
|
|
187
221
|
N --> T[Entity, list and topic tags expire]
|
|
188
222
|
RV --> T
|
|
@@ -202,9 +236,9 @@ Realtime keeps open pages current without polling. The browser asks the BFF for
|
|
|
202
236
|
|
|
203
237
|
A topic is one entity schema, optionally filtered by one field: `{ schema, filter?: { field, eq } }`. Events carry ids only, and the page refetches. One connection per tab carries all of its topics. A `reset` event means the client missed too much and must refetch everything; the first open of a connection also resyncs once, so expect one extra refetch per page load. Pass `onReset`, or a change can be lost. `onAccessChanged` fires when the user's access changes.
|
|
204
238
|
|
|
205
|
-
When the BFF has `secrets`, each ticket answer includes a sealed topic grant, valid for 10 minutes and bound to the session. The revalidate route `POST /api/realtime/revalidate` accepts changes only on topics in that grant, which is how a change
|
|
239
|
+
When the BFF has `secrets`, each ticket answer includes a sealed topic grant, valid for 10 minutes and bound to the session. The revalidate route `POST /api/realtime/revalidate` accepts changes only on topics in that grant, which is how a change written outside the BFF expires the server cache. The client renews the ticket after 8 minutes.
|
|
206
240
|
|
|
207
|
-
To show this in a demo, open `/crm` in two windows and edit a Lead as a Sales manager in one of them. The other window updates without a reload
|
|
241
|
+
To show this in a demo, open `/crm` in two windows and edit a Lead as a Sales manager in one of them. The other window updates without a reload.
|
|
208
242
|
|
|
209
243
|
> **Warning:** Do not open the stream with a hand-written `EventSource`. It cannot send the
|
|
210
244
|
> `Authorization` and `X-Organization-Id` headers that CI needs, and the failure
|
|
@@ -234,7 +268,7 @@ const gateway = defineGateway({
|
|
|
234
268
|
})
|
|
235
269
|
```
|
|
236
270
|
|
|
237
|
-
Adapters for Next, Web Fetch, Express and Nest serve the same gateway kernel. A gateway exposes remote resources and never creates CI schemas: an
|
|
271
|
+
Adapters for Next, Web Fetch, Express and Nest serve the same gateway kernel. A gateway exposes remote resources and never creates CI schemas: an Organization admin connects them through a Knowledge connector and maps fields onto an Organization schema. In NestJS, `bindNestOperation` binds an existing service method without decorators, and the CI entry point does not inherit your HTTP guards, pipes or interceptors, so each entry point keeps its own checks. Start Nest with `NestFactory.create(AppModule, { bodyParser: false })` so the SDK parses bounded JSON, and keep a global prefix off the gateway's `/v1/*` routes.
|
|
238
272
|
|
|
239
273
|
## Related pages
|
|
240
274
|
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Infrastructure
|
|
2
|
+
|
|
3
|
+
The resources that a CI deployment runs, what each one is for, and how the Amazon EKS blueprint maps them to AWS services.
|
|
4
|
+
|
|
5
|
+
The CI deployment that your demo connects to provides every resource on this page. You do not provision or run any of them. This page explains what runs where, so that you know what sits behind the API when your package or your web app calls CI. The [Platform architecture](../platform/architecture.md) page introduces the same parts from the builder's side.
|
|
6
|
+
|
|
7
|
+
## Runtime resources
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart LR
|
|
11
|
+
subgraph outside["Outside the CI deployment"]
|
|
12
|
+
browser["Browser"]
|
|
13
|
+
studio["Studio desktop app"]
|
|
14
|
+
webapp["Your web app (BFF)"]
|
|
15
|
+
end
|
|
16
|
+
subgraph deployment["CI deployment"]
|
|
17
|
+
gateway["Gateway"]
|
|
18
|
+
dashboard["Dashboard and Studio install page"]
|
|
19
|
+
api["Backend API"]
|
|
20
|
+
workers["Background and interactive workers"]
|
|
21
|
+
compute["Compute"]
|
|
22
|
+
media["Media"]
|
|
23
|
+
pg[("PostgreSQL with pgvector")]
|
|
24
|
+
broker["Message broker"]
|
|
25
|
+
storage[("Object storage")]
|
|
26
|
+
end
|
|
27
|
+
ai["AI model providers"]
|
|
28
|
+
browser --> gateway
|
|
29
|
+
studio --> gateway
|
|
30
|
+
webapp -->|"Application API"| gateway
|
|
31
|
+
gateway --> dashboard
|
|
32
|
+
gateway --> api
|
|
33
|
+
gateway --> media
|
|
34
|
+
api --> pg
|
|
35
|
+
workers --> pg
|
|
36
|
+
api -->|"wake signals"| broker
|
|
37
|
+
broker --> workers
|
|
38
|
+
broker -->|"Compute jobs"| compute
|
|
39
|
+
compute -->|"results"| api
|
|
40
|
+
compute -->|"presigned URLs"| storage
|
|
41
|
+
browser -->|"signed upload"| storage
|
|
42
|
+
media -->|"signed source links"| storage
|
|
43
|
+
workers --> ai
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
| Resource | What it is for |
|
|
47
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| Gateway | Receives all HTTP traffic and routes it to the Dashboard, the backend API and Media. |
|
|
49
|
+
| Dashboard | A static web app that calls the backend API for all its data. It also serves the public Studio install page of each Organization, where people download Studio and connect it with one button. |
|
|
50
|
+
| Backend API | Serves every HTTP route that the Dashboard, Studio, the CLI and your app call. It stores long work and returns at once; workers run that work. |
|
|
51
|
+
| Workers | Background workers run long jobs, and interactive workers run the agent and tool work that users wait for. |
|
|
52
|
+
| Compute | Runs transcription, transcoding and conversion from a queue. Each capability has its own slots, so a long transcode does not block transcription. |
|
|
53
|
+
| Media | Serves file bytes and image transforms from URLs that the backend signs. No file byte passes through a backend endpoint. |
|
|
54
|
+
| PostgreSQL | Holds the authoritative data in two databases: one for application data, Knowledge and queued work, and one for datasets. The pgvector extension stores embeddings for semantic search. |
|
|
55
|
+
| Message broker | Carries wake signals from the API to the workers, broadcast events between backend processes, and the job queues of Compute. A wake signal is only a hint: workers find their work in PostgreSQL. |
|
|
56
|
+
| Object storage | Holds every file. Studio installers and updates, and archived rows, have their own stores next to the store for application files. |
|
|
57
|
+
| Cache | There is no separate cache service. Each backend process keeps hot reads, such as schemas, policies and settings, in memory, and broadcast events clear stale entries in every process. |
|
|
58
|
+
| Email provider | Sends platform email. Every message goes through a durable queue in PostgreSQL before the provider receives it. |
|
|
59
|
+
| AI model providers | External model services that agents, Skills and embeddings call. A Tenant admin chooses the available models; the blueprints do not provision them. |
|
|
60
|
+
| Logs | Every backend process and Compute write structured logs, and the CI deployment forwards them to a log service. |
|
|
61
|
+
|
|
62
|
+
## What this means for your code
|
|
63
|
+
|
|
64
|
+
File uploads go straight from the browser to object storage. Your BFF asks CI for an upload slot, and the browser sends the bytes with one signed PUT. A Knowledge file field accepts a file up to its `maxBytes`, and never above the limit of the CI deployment, which is 1 GiB by default and at most 2 GiB. The browser must send the URL, the method and every header that CI returns. Your BFF never streams file bytes. The [External apps](external-apps.md) page shows the flow in the template.
|
|
65
|
+
|
|
66
|
+
Event streams, such as a chat answer, stay open through a heartbeat. The gateway closes a request that sends no bytes for 120 seconds and caps every response at 10 minutes. The backend sends a comment line on every event stream each 20 seconds, so a slow model does not cut the stream. If your BFF forwards a stream, pass each chunk on as it arrives so the heartbeat reaches the browser.
|
|
67
|
+
|
|
68
|
+
Long work is asynchronous. When your app starts an agent run or a workflow, the API stores the run and returns, and a worker runs it. A slow broker delays work, because workers always read their work from PostgreSQL.
|
|
69
|
+
|
|
70
|
+
Configuration changes reach every backend process. When a schema, a policy or a setting changes, a broadcast event clears the cached copy in each process after the write commits. If that event is lost, the cached copy still expires after a short time limit.
|
|
71
|
+
|
|
72
|
+
## The Amazon EKS blueprint
|
|
73
|
+
|
|
74
|
+
A blueprint is the infrastructure code and the deployment configuration that turn the resources above into cloud services. Running CI deployments use the Amazon Elastic Kubernetes Service (EKS) blueprint. Blueprints also exist for Azure Kubernetes Service (AKS) and Azure Container Apps (ACA).
|
|
75
|
+
|
|
76
|
+
The EKS blueprint has three layers. Infrastructure as code creates the AWS foundation: the network, the cluster, the image registry, DNS, and the managed databases and buckets of each CI deployment. Helm charts describe the workloads, and Argo CD keeps the cluster in line with them. Release pins name the exact image of each service, so a new CI release is a change of pins that Argo CD rolls out.
|
|
77
|
+
|
|
78
|
+
```mermaid
|
|
79
|
+
flowchart LR
|
|
80
|
+
users["Browser, Studio and your web app"]
|
|
81
|
+
cdn["Amazon CloudFront"]
|
|
82
|
+
nlb["Network Load Balancer"]
|
|
83
|
+
subgraph eks["Amazon EKS cluster"]
|
|
84
|
+
gateway["Envoy Gateway"]
|
|
85
|
+
dashboard["Dashboard"]
|
|
86
|
+
api["Backend API"]
|
|
87
|
+
workers["Workers"]
|
|
88
|
+
compute["Compute"]
|
|
89
|
+
media["Media"]
|
|
90
|
+
rabbit["RabbitMQ"]
|
|
91
|
+
end
|
|
92
|
+
rds[("Amazon RDS for PostgreSQL or CloudNativePG")]
|
|
93
|
+
s3[("Amazon S3")]
|
|
94
|
+
ses["Amazon SES"]
|
|
95
|
+
secrets["AWS Secrets Manager"]
|
|
96
|
+
ecr["Amazon ECR"]
|
|
97
|
+
users --> nlb
|
|
98
|
+
users -->|"media URLs"| cdn
|
|
99
|
+
cdn --> nlb
|
|
100
|
+
nlb --> gateway
|
|
101
|
+
gateway --> dashboard
|
|
102
|
+
gateway --> api
|
|
103
|
+
gateway --> media
|
|
104
|
+
api --> rds
|
|
105
|
+
workers --> rds
|
|
106
|
+
api --> rabbit
|
|
107
|
+
rabbit --> workers
|
|
108
|
+
rabbit --> compute
|
|
109
|
+
compute --> s3
|
|
110
|
+
media --> s3
|
|
111
|
+
eks -->|"email"| ses
|
|
112
|
+
secrets -.->|"credentials"| eks
|
|
113
|
+
ecr -.->|"images"| eks
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
| Resource | AWS service |
|
|
117
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| Containers | Amazon EKS with a managed node group. Images come from Amazon Elastic Container Registry (ECR). |
|
|
119
|
+
| Gateway | Envoy Gateway behind a Network Load Balancer. Amazon Route 53 holds the DNS records, and cert-manager issues the certificates. |
|
|
120
|
+
| PostgreSQL | Amazon Relational Database Service (RDS) for PostgreSQL in private subnets, or CloudNativePG in the cluster on encrypted Amazon Elastic Block Store (EBS) volumes. Each CI deployment chooses one. |
|
|
121
|
+
| Message broker | RabbitMQ in the cluster. |
|
|
122
|
+
| Object storage | Amazon Simple Storage Service (S3) buckets for the files and the archive of each CI deployment, and shared buckets for Studio releases. |
|
|
123
|
+
| Media CDN | Amazon CloudFront in front of Media. |
|
|
124
|
+
| Email | Amazon Simple Email Service (SES). |
|
|
125
|
+
| Secrets | AWS Secrets Manager. External Secrets copies the values into the cluster. |
|
|
126
|
+
| Workload identity | EKS Pod Identity, so pods reach S3 and Secrets Manager without stored keys. |
|
|
127
|
+
| Logs and metrics | Datadog receives the logs. Amazon CloudWatch Container Insights collects the cluster metrics. |
|
|
128
|
+
|
|
129
|
+
One EKS cluster can host several CI deployments. Each CI deployment has its own Kubernetes namespace with its own backend, Compute, database, message broker and storage, and it can hold several Organizations. All CI deployments on the cluster share the gateway and Media.
|
|
130
|
+
|
|
131
|
+
## Next pages
|
|
132
|
+
|
|
133
|
+
- [Platform architecture](../platform/architecture.md): Tenants, Organizations, surfaces and the three integration models.
|
|
134
|
+
- [External apps](external-apps.md): Build the web app that calls CI, including direct uploads.
|
|
135
|
+
- [Knowledge](../data/knowledge.md): Records, schemas and semantic search on PostgreSQL.
|
|
@@ -124,9 +124,9 @@ import { useQuery } from "@tanstack/react-query"
|
|
|
124
124
|
|
|
125
125
|
The template's own pages use the template's shadcn/ui package, `@acme/ui`. `ui-react` appears in the Studio widget and in SDK toasts.
|
|
126
126
|
|
|
127
|
-
### Server SDK subpaths
|
|
127
|
+
### Server SDK subpaths an external app uses
|
|
128
128
|
|
|
129
|
-
`external-apps-server-sdk` runs only on your server, because it holds the application's client secret. Each framework peer loads only from its own subpath: `/next` loads `next`, while `/effect` loads no `next`, `pg` or `drizzle-orm`. Administrative APIs exist only on `/admin` and never reach the browser proxy.
|
|
129
|
+
`external-apps-server-sdk` runs only on your server, because it holds the application's client secret. Each framework peer loads only from its own subpath: `/next` loads `next`, while `/effect` loads no `next`, `pg` or `drizzle-orm`. Administrative APIs exist only on `/admin` and never reach the browser proxy. An external app uses four subpaths:
|
|
130
130
|
|
|
131
131
|
| Subpath | What you get |
|
|
132
132
|
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
package/docs/guide/index.md
CHANGED
|
@@ -28,14 +28,14 @@ flowchart LR
|
|
|
28
28
|
|
|
29
29
|
1. Generate a new repository from `next-effect-app` and rename the `@acme` packages. [The solution template](template/index.md) explains the layout you get.
|
|
30
30
|
2. Choose the primitives for the scenario. [Choosing primitives](scenarios/index.md) maps common demo scenarios to the parts that fit them.
|
|
31
|
-
3. Declare entities, access and AI parts in the packages' `ci/` folders. The [Data](data/
|
|
31
|
+
3. Declare entities, access and AI parts in the packages' `ci/` folders. The [Data resources](data/index.md), [AI](ai/index.md) and [Grants and permissions](platform/access.md) pages describe each declaration.
|
|
32
32
|
4. Build the screens and server routes of the web app with the [SDKs](develop/sdks.md), following the patterns in [External apps](develop/external-apps.md).
|
|
33
33
|
5. Deploy the package to an Organization with `ci deploy`, as [Extensions](develop/extensions.md) describes, and point the web app at that Organization.
|
|
34
34
|
|
|
35
35
|
## Sections
|
|
36
36
|
|
|
37
37
|
- [Platform](platform/architecture.md): What CI is made of, how people and apps enter it, and how access works.
|
|
38
|
-
- [Data](data/
|
|
38
|
+
- [Data resources](data/index.md): Where data lives: the Data resources Knowledge, Datasets and Documents, and the connectors that fill them.
|
|
39
39
|
- [AI](ai/index.md): Tools, Skills, Agents and workflows, and how they combine.
|
|
40
40
|
- [Build](develop/sdks.md): The SDKs, extension packages and external apps you write.
|
|
41
41
|
- [Template](template/index.md): The layout of `next-effect-app` and its state machine approach.
|
|
@@ -43,7 +43,7 @@ flowchart LR
|
|
|
43
43
|
|
|
44
44
|
## Where to begin
|
|
45
45
|
|
|
46
|
-
If you are starting a new demo, read [Platform architecture](platform/architecture.md) first, then [The solution template](template/index.md), and use [Choosing primitives](scenarios/index.md) to plan the scenario. If you are adding a feature to a demo that already runs, go straight to the page for that part: data questions belong in Data, model and automation questions in AI, and code questions in Build.
|
|
46
|
+
If you are starting a new demo, read [Platform architecture](platform/architecture.md) first, then [The solution template](template/index.md), and use [Choosing primitives](scenarios/index.md) to plan the scenario. If you are adding a feature to a demo that already runs, go straight to the page for that part: data questions belong in Data resources, model and automation questions in AI, and code questions in Build.
|
|
47
47
|
|
|
48
48
|
## For agents
|
|
49
49
|
|
|
@@ -58,19 +58,23 @@ GITHUB_TOKEN=$(gh auth token) opensrc path collective-intelligence-solutions/sdk
|
|
|
58
58
|
## Pages
|
|
59
59
|
|
|
60
60
|
- Platform
|
|
61
|
-
- [Platform architecture](platform/architecture.md): The parts of Collective Intelligence, the three integration models, and how a
|
|
62
|
-
- [Entrypoints](platform/entrypoints.md): The ways people, apps and agents enter CI at runtime, and the package subpaths that
|
|
61
|
+
- [Platform architecture](platform/architecture.md): The parts of Collective Intelligence, the three integration models, and how a package moves from build to install.
|
|
62
|
+
- [Entrypoints](platform/entrypoints.md): The ways people, apps and agents enter CI at runtime, and the package subpaths that your code imports.
|
|
63
63
|
- [Grants and permissions](platform/access.md): How CI decides what a user, a Group, an app or an API key may do, and how to change it in the template.
|
|
64
|
-
- Data
|
|
65
|
-
- [
|
|
64
|
+
- Data resources
|
|
65
|
+
- [Data resources](data/index.md): Choose between Knowledge, Datasets and Documents, and see where each kind keeps its data.
|
|
66
|
+
- [Knowledge](data/knowledge.md): Declare schemas, store typed records, query them, and read and watch them from an external app.
|
|
66
67
|
- [Datasets](data/datasets.md): Query typed tables of measurements, events and warehouse data, and control who can read them.
|
|
68
|
+
- [Documents](data/documents.md): Keep files in Document Collections, sync them from Microsoft 365 or Google Drive, control who reads them, and know when their content becomes searchable.
|
|
67
69
|
- [Connectors](data/connectors.md): Connect outside systems, map their fields to Knowledge schemas, and run and watch imports.
|
|
68
70
|
- AI
|
|
69
71
|
- [AI primitives](ai/index.md): Tools, Skills, Agents, workflows and Studio chat, how they compose, and how audiences, approvals, models, runs and timeouts behave.
|
|
72
|
+
- [Studio](ai/studio.md): How Organization members work in the Studio desktop app, how a package ships Studio apps, forms and widgets, and how Studio shares one solution with your external application.
|
|
70
73
|
- Build
|
|
71
74
|
- [SDKs](develop/sdks.md): Which @collective-intelligence package to import, from which subpath, with which Effect setup and which versions.
|
|
72
75
|
- [Extensions](develop/extensions.md): What a package declares, how the template wires it, how to deploy it with ci deploy, and the rules its code runs under.
|
|
73
76
|
- [External apps](develop/external-apps.md): Sign users in with CI, read and write their data through a BFF, cache shared reads and stay live with Realtime.
|
|
77
|
+
- [Infrastructure](develop/infrastructure.md): The resources that a CI deployment runs, what each one is for, and how the Amazon EKS blueprint maps them to AWS services.
|
|
74
78
|
- Template
|
|
75
79
|
- [The solution template](template/index.md): 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.
|
|
76
80
|
- [State machines](template/state-machines.md): How next-effect-app models UI flows as XState machines with Effect actors, keeps server data in the QueryCache, resends uncertain writes safely, and checks hard flows with Models.
|
|
@@ -44,11 +44,31 @@ A grant change takes effect within 60 seconds. Every Organization-scoped respons
|
|
|
44
44
|
|
|
45
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
46
|
|
|
47
|
-
Groups
|
|
47
|
+
## Groups
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
Groups are the usual way to hand out grants. A Group is a named set of accounts in one Organization: users, and service principals that a package places in its own Groups. Groups form a tree in which each Group has at most one parent, and an Organization allows at most five levels.
|
|
50
|
+
|
|
51
|
+
A grant to a Group has one recipient, the Group, and CI applies it to every account that it reaches. The grant's `coverage` decides which accounts these are:
|
|
52
|
+
|
|
53
|
+
- With `coverage: "direct"`, the grant reaches the members of that Group only.
|
|
54
|
+
- With `coverage: "inherited"`, it also reaches the members of every Group below it, at any depth.
|
|
55
|
+
|
|
56
|
+
Inheritance goes down the tree only. A grant to a parent Group can reach the members of its subgroups, and a grant to a subgroup never reaches the members of its parent. Every grant must state its `coverage`. In a Resource Audience, a Group entry without `coverage` counts as `inherited`.
|
|
57
|
+
|
|
58
|
+
The template shows both directions. It grants the Sales rep profile to Sales and the Sales manager profile to Sales managers, both with `inherited` coverage:
|
|
59
|
+
|
|
60
|
+
```mermaid
|
|
61
|
+
flowchart TD
|
|
62
|
+
S["Sales<br/>grant: Sales rep, inherited"] --> M["Sales managers<br/>grant: Sales manager, inherited"]
|
|
63
|
+
```
|
|
50
64
|
|
|
51
|
-
A
|
|
65
|
+
A member of Sales managers holds both profiles, because Sales is an ancestor of their Group. A member who is only in Sales holds Sales rep and nothing from the managers grant.
|
|
66
|
+
|
|
67
|
+
CI stores the grants that reach each account and recalculates them in the same write that adds or removes a Group member, moves a Group or changes a grant. A request reads that stored result and does not walk the tree. A workflow also reads the current Groups of its run identity at every tool call, so a person you remove from a Group loses that access at the next call. Clients see the change within 60 seconds.
|
|
68
|
+
|
|
69
|
+
### Declared Groups and Dashboard Groups
|
|
70
|
+
|
|
71
|
+
A package declares a Group tree with `declareOrganizationGroup`, and every Group in the tree has an FQN. 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
72
|
|
|
53
73
|
```ts
|
|
54
74
|
export const salesGroupFqn = "acme.app.groups.sales"
|
|
@@ -75,9 +95,18 @@ export const salesGroup = declareOrganizationGroup({
|
|
|
75
95
|
})
|
|
76
96
|
```
|
|
77
97
|
|
|
78
|
-
|
|
98
|
+
A Group that someone creates in the Dashboard, or with `ci.access.groups.create` from a server, has no FQN. Package grants and the server SDK name a Group only by its FQN, so a Group without one can get grants only in the Dashboard.
|
|
99
|
+
|
|
100
|
+
Declared Groups follow these rules:
|
|
101
|
+
|
|
102
|
+
- Only the package that first declared a Group FQN can declare it again. FQNs that start with `core.groups.` belong to the platform, and a package install that uses one fails.
|
|
103
|
+
- With `upsert`, each deploy writes the declared name, description and parent again. With `init_only`, CI keeps a Group that already exists as it is.
|
|
104
|
+
- The package never fills its Groups. After install, an Organization admin adds people to Sales or Sales managers. The one exception is a service principal that the same package declares with `groups`, which the install places in those Groups.
|
|
105
|
+
- When a release drops a Group, CI deletes it only when nothing uses it, and keeps it otherwise. A Group that holds an Access Grant cannot be deleted.
|
|
106
|
+
|
|
107
|
+
## Declared and runtime grants
|
|
79
108
|
|
|
80
|
-
|
|
109
|
+
A package can declare capabilities, profiles, policies, Max Privileges and grants, and the install creates them in the Organization. The lifecycle of each grant decides who owns it after install. The template's Sales grant uses `deployMode: "init_only"` with `readonly: false`, so an Organization admin 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
110
|
|
|
82
111
|
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
112
|
|
|
@@ -96,7 +125,7 @@ await ci.access.grants.sync({
|
|
|
96
125
|
// result = { created, updated, deleted, unchanged }: Access Grant FQNs.
|
|
97
126
|
```
|
|
98
127
|
|
|
99
|
-
The app's server acts only with the grants an
|
|
128
|
+
The app's server acts only with the grants that an Organization admin 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
129
|
|
|
101
130
|
## Data policies narrow records
|
|
102
131
|
|
|
@@ -168,7 +197,7 @@ Consent is a separate setting. `applicationConsent` (`inherit`, `ask` or `skip`)
|
|
|
168
197
|
|
|
169
198
|
## API keys and service principals
|
|
170
199
|
|
|
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
|
|
200
|
+
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. The convert-lead workflow selects it with `runIdentity: { mode: "service_principal", servicePrincipal: convertLeadRunnerFqn }`. In this mode, a production run that a person starts from Studio or the Dashboard, and a run that no person starts, act as `convertLeadRunner`. A call from the web app with a user's delegated token still acts as that user, so when a signed-in user clicks Convert, the run acts as that user. [AI primitives](../ai/index.md) lists every case.
|
|
172
201
|
|
|
173
202
|
An API key belongs to a service principal and is created with a Max Privileges template:
|
|
174
203
|
|
|
@@ -178,12 +207,13 @@ ci api-keys upsert --principal <fqn> --name <name> --max-privileges <template-fq
|
|
|
178
207
|
|
|
179
208
|
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
209
|
|
|
181
|
-
> **Warning:** A run as a service principal asks no questions and decides no approvals.
|
|
182
|
-
> approval gates do not stop it: CI approves unattended
|
|
183
|
-
> records
|
|
184
|
-
>
|
|
210
|
+
> **Warning:** A run as a service principal asks no questions and decides no approvals. In an
|
|
211
|
+
> Agent run, tool approval gates do not stop it: CI approves the unattended call
|
|
212
|
+
> by default and records it without an actor. A workflow Approval node still
|
|
213
|
+
> pauses the run until a person decides, and that reviewer never becomes the
|
|
214
|
+
> run's identity. Plan for this before a demo drives an agent with an API key.
|
|
185
215
|
|
|
186
|
-
The template's server also reads Leads with the app's own
|
|
216
|
+
The template's server also reads Leads with the app's own Server Credential (the Read Port on the [External apps](../develop/external-apps.md) page). The package declares no `{ applicationServer }` grant for it, so an Organization admin must give the app server read access to Leads after install.
|
|
187
217
|
|
|
188
218
|
## Hide in the UI, check on the server
|
|
189
219
|
|
|
@@ -214,16 +244,51 @@ The template's CRM page has a Convert action that starts the convert-lead workfl
|
|
|
214
244
|
|
|
215
245
|
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
246
|
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.
|
|
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 }`.
|
|
247
|
+
3. Know who the run acts as. The BFF route starts the workflow with the signed-in user's delegated token, so the run acts as that user, with the user's current grants, and not as `convertLeadRunner`. The workflow's only node sets a run variable (`converted: true`) and writes no Lead record, so no Knowledge write policy takes part. Confirm it with one trial run as a rep before the demo.
|
|
248
|
+
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 }`. In the Dashboard Check access tab, choose that user and `platform.workflows` to see which grant gives it. Allow up to 60 seconds after a grant change, or wait for the realtime access event to refresh the page.
|
|
219
249
|
|
|
220
|
-
For a one-off demo you can skip the package change. An
|
|
250
|
+
For a one-off demo you can skip the package change. An Organization admin 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, so remove the runtime grant when the demo ends.
|
|
221
251
|
|
|
222
252
|
## Debug and test access
|
|
223
253
|
|
|
224
|
-
To answer "why can or can't this user do this?",
|
|
254
|
+
To answer "why can or can't this user do this?", use the access check. It lists the principal's grants and how each one reaches it: directly, through a Group, or through an ancestor Group. For a capability, it names the grants that hold it. For one Knowledge record, it lists each policy of the schema and why the policy admits the record or not. You can reach the same check in three ways, and each one needs `admin.grants` at read. The built-in Organization admin and Organization operator profiles hold it, and the Studio user profile does not.
|
|
255
|
+
|
|
256
|
+
The short path for a person is the Dashboard. Open the Organization admin Access page and its Check access tab, then choose who and a capability or a Knowledge record. On a member's page, the Effective access tab lists every capability with a Why? or Why not? button that opens Check access with the member and the capability filled in.
|
|
257
|
+
|
|
258
|
+
From an MCP client, call the `explain_access` tool. Its `request` takes the principal, the target and, optionally, the credential whose Max Privileges CI must apply. On `/mcp`, name the Organization with `organization_id`; on `/mcp/o/<organizationId>` you can leave it out.
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{
|
|
262
|
+
"name": "explain_access",
|
|
263
|
+
"arguments": {
|
|
264
|
+
"organization_id": "<organization id>",
|
|
265
|
+
"request": {
|
|
266
|
+
"principal": { "kind": "user", "userId": "<user id>" },
|
|
267
|
+
"target": {
|
|
268
|
+
"kind": "capability",
|
|
269
|
+
"code": "platform.workflows",
|
|
270
|
+
"mode": "on"
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
From server code, call `ci.access.explain` in the server SDK with the same request. Add a `credential` of kind `application_token` to see the access through the app, after the Max Privileges cut:
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
const why = await ci.access.explain({
|
|
281
|
+
organizationId,
|
|
282
|
+
principal: { kind: "user", userId },
|
|
283
|
+
target: { kind: "capability", code: "platform.workflows", mode: "on" },
|
|
284
|
+
credential: { kind: "application_token", applicationId }
|
|
285
|
+
})
|
|
286
|
+
// why.target.allowed and why.target.holders, why.grants with their path, why.cut
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
The template's app server holds no grant with `admin.grants`, so this call answers 403 from the template's server as installed. Use the Dashboard or the MCP tool there.
|
|
225
290
|
|
|
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
|
|
291
|
+
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 the app's client secret must have been rotated with `ci apps rotate-secret <application-id>`. Install adds no members to the Groups and does not rotate the secret. A package that declares grants also needs an install with a user's management token, because a system install fails with `installer_required`.
|
|
227
292
|
|
|
228
293
|
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
294
|
|