Skip to content

Commit beb060d

Browse files
kinqsradiokinqsradio
authored
Merge pull request #231 from kinqsradio/docs/current-product-reference
docs: refresh product overview and current service contracts
2 parents daa564d + 6dee430 commit beb060d

14 files changed

Lines changed: 517 additions & 242 deletions

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Anh Dang
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 117 additions & 90 deletions
Large diffs are not rendered by default.

‎docs/README.md‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,22 @@
11
# Orbyn documentation
22

3+
Orbyn is developed in public by Anh Dang, a University of Melbourne student.
4+
See the [creator/contact details](../README.md#creator-and-contact),
5+
[contribution workflow](../README.md#contributing) and
6+
[MIT application license](../LICENSE).
7+
38
Start with the guide for the task. Current implementation and configuration define
49
the contract; check the owning source when a guide and code disagree. Old ADR
510
queues and checkpoint transcripts have been retired from the active tree.
611

12+
## Product overview
13+
14+
Orbyn covers tasks, calendars, projects, documents, study and assistant work across
15+
web/desktop and mobile. Start with [the repository overview](../README.md),
16+
[Assistant](assistant.md), [Docs architecture](architecture.md#workspace-and-document-ownership)
17+
and [Admin Publishing](admin-publishing.md). Features that need rollout flags,
18+
provider consent or external service setup describe those conditions in their guide.
19+
720
## Develop Orbyn
821

922
| Need | Guide |
@@ -22,16 +35,18 @@ queues and checkpoint transcripts have been retired from the active tree.
2235

2336
## Product and operations
2437

25-
| Need | Guide | Owning source |
26-
| ------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
27-
| Local environment and services | [Setup](setup.md), [environment](environment.md) | `compose.yaml`, `.env.example`, `backend/src/config/env.ts` |
28-
| Architecture and data flow | [Architecture](architecture.md) | `backend/src/app.ts`, shared packages and owning modules |
29-
| HTTP contract | [API](api.md), [OpenAPI](openapi.yaml) | Backend routes and shared schemas |
30-
| MCP connector | [MCP](mcp.md), [catalog](mcp-catalog.json), [runbook](runbooks/agents.md) | `backend/src/modules/mcp-server/`, `backend/src/capabilities/` |
31-
| Plugin service | [Plugin](plugin.md) | `backend/src/modules/plugin/` |
32-
| Mobile app | [Mobile](mobile.md) | `mobile/package.json`, app configuration and screens |
33-
| Deployment and recovery | [Deployment](deployment.md), [scalability](scalability.md) | Deployment scripts, Compose and Kubernetes manifests |
34-
| Hosted planner usage | [Connector skill](agent-skill/orbyn/SKILL.md) | Public tool contract, separate from developer-agent workflow |
38+
| Need | Guide | Owning source |
39+
| ------------------------------------ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
40+
| Local environment and services | [Setup](setup.md), [environment](environment.md) | `compose.yaml`, `.env.example`, `backend/src/config/env.ts` |
41+
| Architecture and data flow | [Architecture](architecture.md) | `backend/src/app.ts`, shared packages and owning modules |
42+
| HTTP contract | [API](api.md), [OpenAPI](openapi.yaml) | Backend routes and shared schemas |
43+
| Assistant chats and automation | [Assistant](assistant.md), [conversation API](api.md#retained-assistant-conversations) | `backend/src/modules/assistant-workspace/`, `backend/src/modules/ai/` |
44+
| Changelog, image drafts and LinkedIn | [Admin Publishing](admin-publishing.md) | `backend/src/modules/publishing/`, web admin UI |
45+
| MCP connector | [MCP](mcp.md), [catalog](mcp-catalog.json), [runbook](runbooks/agents.md) | `backend/src/modules/mcp-server/`, `backend/src/capabilities/` |
46+
| Plugin service | [Plugin](plugin.md) | `backend/src/modules/plugin/` |
47+
| Mobile app | [Mobile](mobile.md) | `mobile/package.json`, app configuration and screens |
48+
| Deployment and recovery | [Deployment](deployment.md), [scalability](scalability.md) | Deployment scripts, Compose and Kubernetes manifests |
49+
| Hosted planner usage | [Connector skill](agent-skill/orbyn/SKILL.md) | Public tool contract, separate from developer-agent workflow |
3550

3651
These product references describe application behavior; changing development
3752
skills does not by itself change API routes, security controls or deployment.

‎docs/api.md‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2306,6 +2306,44 @@ Apps can also connect by signing in with Orbyn (OAuth 2.1 with PKCE S256 for eve
23062306

23072307
Only a person signed in to Orbyn can use these: personal API keys get `403`, and agent credentials get `401`. Making and revoking a key is in the audit log (`agent_key.created`, `agent_key.revoked`), with the request id. A connection that goes over its limits more than 5 times, or is refused more than 50 times, within ten minutes is paused until you restore it (`agent_grant.suspended`, `agent_grant.restored`).
23082308

2309+
## Retained assistant conversations
2310+
2311+
These are first-party session endpoints owned by
2312+
`backend/src/modules/assistant-workspace/conversation-routes.ts`; MCP/plugin
2313+
credentials do not grant access. Responses use `Cache-Control: private, no-store`
2314+
and current account/source authority. The schemas in
2315+
`packages/core/src/assistant-conversation.ts` own exact response fields.
2316+
2317+
| Method and path | Contract |
2318+
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2319+
| `GET /me/assistant/conversation` | Read rollout availability and an existing personal destination; does not create it |
2320+
| `POST /me/assistant/conversation` | Explicitly open/create the signed-in person's personal destination |
2321+
| `GET /me/assistant/conversation/for-chat/:id` | Resolve an existing owned chat destination |
2322+
| `GET /me/assistant/conversations/:id` | Authorized feed with `after`, optional `through`, and `limit` (1–100, default 50); sequence cursors are strings |
2323+
| `GET /me/assistant/conversations/:id/entries/:entryId` | Resolve an available entry's destination and sequence |
2324+
| `GET /me/assistant/conversations/:id/entries/:entryId/details` | Read current entry, source titles and execution/question availability under one primary repeatable-read snapshot; no acknowledgement or execution side effect |
2325+
| `POST /me/assistant/conversations/:id/read` | Acknowledge only displayed entries with `{ "through": "positive sequence" }` |
2326+
| `POST /me/assistant/conversations/:id/entries/:entryId/answer` | Resume an available question with `{ "answer", "turn_id" }`; plain chat replies do not implicitly answer a waiting job |
2327+
| `GET /me/assistant/conversation/preferences` | Read current conversation alert preferences |
2328+
| `PATCH /me/assistant/conversation/preferences` | Set `{ "muted": true/false }` independently of job admission |
2329+
| `GET /me/assistant/work-controls` | Read Background/Overnight admission pauses |
2330+
| `PATCH /me/assistant/work-controls` | Set `background_paused` and/or `overnight_paused`; existing jobs continue |
2331+
| `GET /me/assistant/conversations/:id/history` | Read authorized saved legacy history through its separately validated query contract |
2332+
2333+
The conversation flag defaults off. The personal-home read reports
2334+
`{ "enabled": false, "destination": null }` when off; rollout-gated feed,
2335+
entry, answer and preference endpoints return 404. Saved history and work
2336+
controls remain independently available. A missing, retired or inaccessible
2337+
entry cannot be reconstructed from client-supplied content.
2338+
2339+
`POST /ai/chat/start` accepts `reply_to_entry_id` and optional `reply_excerpt`
2340+
(1–2,000 characters) alongside the existing `chat_id`, `turn_id` and message.
2341+
The server validates the excerpt against the exact authorized target, retains its
2342+
revision/dependencies and rechecks authority at provider/effect boundaries.
2343+
A retry cannot reuse a turn identity for changed text, target or excerpt.
2344+
See [Assistant](assistant.md) for client behavior and
2345+
[deployment](deployment.md#unified-conversation-rollout-opt-in) for rollout.
2346+
23092347
## AI assistant
23102348

23112349
### `PUT /planner/prefs` — daily digest
@@ -2382,9 +2420,8 @@ it: `minutes` is then at most 25). `reasons` are short sentences, most important
23822420
### `POST /ai/chat/start` (auth, 10/min)
23832421

23842422
Starts an assistant turn and returns `202 { "id": "job uuid" }` at once. The body is the same as
2385-
`POST /ai/chat` below. The turn runs on the server for as long as the model needs (up to ten
2386-
minutes), so a proxy's limit on one request (Cloudflare gives an origin 100 seconds) never cuts
2387-
it off. Returns `503` when no provider is set up.
2423+
`POST /ai/chat` below. The durable job runs on the server within its configured runtime and token
2424+
budgets; a proxy timeout on the admission/polling request does not own the job's lifetime. Returns `503` when no provider is set up.
23882425

23892426
### `GET /ai/chat/:id` (auth)
23902427

‎docs/architecture.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@ live on different machines; see [scalability.md](scalability.md).
3535
| `pdf` | `services/pdf.ts` | Private bounded document renderer |
3636
| `measure` | `services/measure.ts` | Optional semantic indexing worker; `semantic` Compose profile |
3737

38-
`server.ts` runs every module in one process for local development and tests.
38+
`server.ts` combines the HTTP modules and status prober for local development.
39+
It does not replace the notifier, Background/Overnight, conversion or plugin
40+
inference workers. Compose and production launch their owning service entry points.
3941
`services/http.ts` gives every HTTP service the same setup: CORS, rate limiting, conditional GETs
4042
with `ETag`, `GET /live` (liveness, no database) and `GET /health` (readiness).
4143

@@ -44,6 +46,20 @@ MCP workspace-AI requests validate the shared, provider-free
4446
execution remains in the inference worker through `provider-policy.ts`; request
4547
handlers do not import the provider adapters merely to validate input.
4648

49+
## Assistant conversations and execution
50+
51+
The Assistant has personal and project chats, retained timeline entries and
52+
separate durable execution jobs. Background and Overnight results can publish
53+
back to their captured conversation when the opt-in conversation flag is enabled;
54+
they do not become new user-facing chats for every execution. Publication, alerts
55+
and model execution have separate ownership and current-access checks.
56+
57+
[Assistant](assistant.md) describes the current client flow and rollout boundary.
58+
The [API guide](api.md#retained-assistant-conversations) covers feed, details,
59+
reply/excerpt, read-state and work-control contracts. Source lives in
60+
`modules/assistant-workspace/`, `modules/ai/` and
61+
`packages/core/src/assistant-conversation.ts`.
62+
4763
## Workspace and document ownership
4864

4965
The web app keeps one shared planner and independent pane controllers. Each pane

‎docs/assistant.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Assistant
2+
3+
Orbyn combines personal and project chats with durable Background and Overnight
4+
work. The backend owns orchestration, provider calls, permissions and execution;
5+
clients display retained messages and current work state.
6+
7+
## Chats and Activity
8+
9+
**Chats** groups the personal Orbyn conversation, project chats, pinned chats
10+
and recent chats. New project chats require a project before sending. **Activity**
11+
opens Background, Overnight and Upcoming work. Execution jobs remain independent
12+
of the conversation that receives their results.
13+
14+
With unified conversations enabled, completed work, questions and summaries return
15+
to the captured conversation. Scheduled nights group results by delivery window
16+
and destination. They do not create a new sidebar chat for every run. When the
17+
flag is off, the existing chat/activity paths remain available.
18+
19+
Messages offer Copy and Details. Details shows currently accessible sources and
20+
work state; Answer resumes an available waiting question, and Review opens the
21+
existing approval flow. Stop work is available through Details. Collapsed user
22+
messages retain their full text for expansion and copying.
23+
24+
On web, selecting answer text offers **Ask Orbyn** after the selection settles.
25+
On mobile, Message options opens an excerpt-selection sheet. Both add a removable
26+
excerpt to the existing composer without sending it or discarding typed text.
27+
The excerpt names an exact authorized entry and is limited to 2,000 characters.
28+
Changed or unavailable source content cannot silently reuse that reply context.
29+
30+
The web workspace uses Chats and detail panels around one conversation scroller.
31+
Narrow panes use local sheets/panels; mobile uses its own drawer and keyboard-aware
32+
composer. Panels retain drafts and reading state when opened or closed.
33+
34+
## Background and Overnight
35+
36+
Background and Overnight run in separate service processes with persisted jobs,
37+
checkpoints, leases, budgets and current-access checks. Interactive requests keep
38+
their own reserved runtime capacity. A result's conversation destination does not
39+
change which process owns its execution.
40+
41+
Overnight is opt-in. Its schedule, quiet hours and review controls belong to the
42+
person's assistant settings. Upcoming can pause new Background or Overnight
43+
admissions independently; pausing does not stop already-admitted jobs. Muting
44+
conversation alerts is also separate from stopping execution or revoking access.
45+
46+
Actions follow current assistant grants and team permissions. Unattended deletion,
47+
outside email, teammate notifications and publishing require Review. An answer or
48+
an excerpt is context for a request, never extra permission.
49+
50+
## Configuration and rollout
51+
52+
Select providers and models in **Admin → AI**. Configure service encryption keys,
53+
private service addresses and rollout flags in the server environment; see
54+
[setup](setup.md#ai-providers) and [environment](environment.md). Provider availability
55+
and personal-account transports have their own configuration and consent boundaries.
56+
57+
`ASSISTANT_CONVERSATION_ENABLED` defaults to `false`. The retained timeline and
58+
associated UI are implemented in main, but a deployment must explicitly enable
59+
the flag consistently for API, AI, Background and Overnight. Required migrations,
60+
rollback behavior and history retention are documented in
61+
[deployment](deployment.md#unified-conversation-rollout-opt-in).
62+
63+
The implementation records preserve local web/Expo-web qualification. They do not
64+
establish the configuration of a hosted instance, installed-native behavior or a
65+
live external provider's availability. See [verification](verification.md).
66+
67+
## Contract owners
68+
69+
| Contract | Source |
70+
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
71+
| Feed, source visibility, replies, read state and work controls | `backend/src/modules/assistant-workspace/` |
72+
| Interactive jobs and orchestration | `backend/src/modules/ai/` |
73+
| Shared retained-entry and reply schemas | `packages/core/src/assistant-conversation.ts`, `packages/core/src/schemas.ts` |
74+
| Web UI | `desktop/src/features/assistant/` |
75+
| Mobile UI | `mobile/src/screens/AssistantScreen.tsx`, `mobile/src/components/AssistantDrawer.tsx` |
76+
77+
See the [API contract](api.md#retained-assistant-conversations),
78+
[architecture](architecture.md#assistant-conversations-and-execution) and
79+
[mobile guide](mobile.md).

0 commit comments

Comments
 (0)