Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions hub/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Hub is being rebuilt. The [Hub overview](../README.md) describes what the baseli
- [Telemetry](telemetry.md): explicit OpenTelemetry spans, safe attributes, and process lifetime.
- [Background jobs](background-jobs.md): PostgreSQL queues, workers, schedules, setup, and test isolation.
- [Learning foundation](learning-foundation.md): Copilot connection, private storage, secure command execution, and deferred repository seams.
- [Review collaboration backend](review-collaboration.md): persisted threads, product APIs, authorization, deletion state, and the learning snapshot seam.
- [WebSocket updates](websockets.md): local broadcasts, subscriptions, access hooks, and connection limits.
- [Testing and operations](testing-and-operations.md): baseline checks and their limits.
- [Storybook](storybook.md): retained presentation, fixtures, and screenshot evidence.
Expand Down
6 changes: 3 additions & 3 deletions hub/docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Hub contributors are rebuilding the app on `build/hub/new` before merging it int

The team has chosen TypeScript, Express for the API, React and Vite for the frontend, and Vitest for tests. The old backend and the frontend code that connected to it have been removed rather than rewritten.

The API responds to a health check and gives signed-in members read access to the seeded repository index, prototype details, and Build history, plus prototype metadata edits and draft registration. The frontend connects the retained pages for local exploration. Storybook remains the presentation workbench.
The API responds to a health check and gives signed-in members access to the seeded repository index, prototype details, Build history, prototype metadata edits, draft registration, and persisted prototype review conversations. The frontend connects the retained pages for local exploration. Storybook remains the presentation workbench.

Contributors can use PostgreSQL and Prisma locally or in the devcontainer. The database has a provider-neutral identity transaction foundation with explicit GitHub and single-tenant Microsoft Entra sign-in adapters. A reusable deployment bootstrap secret can enroll a verified provider identity as a Hub administrator. Members can browse a seeded repository index and edit visible prototype metadata through the API. The app cannot yet discover real repositories, import Builds, host published previews, or support live multi-user reviews.
Contributors can use PostgreSQL and Prisma locally or in the devcontainer. The database has a provider-neutral identity transaction foundation with explicit GitHub and single-tenant Microsoft Entra sign-in adapters. A reusable deployment bootstrap secret can enroll a verified provider identity as a Hub administrator. Members can browse the repository index, edit visible prototype metadata, and use the review-comment API for persisted conversations. The app cannot yet discover real repositories, import Builds, host published previews, connect the retained review UI to the new API, or deliver live multi-user updates.

The [production runtime](deployment.md) serves the built frontend and API and runs both workers in one image. Deployment runs database and job setup separately before starting that image. The Azure installation uses an explicit startup entrypoint to retrieve configured Key Vault values through each workload's managed identity before importing provisioning, setup, or runtime code. Local entrypoints and direct environment configuration remain unchanged.

Expand Down Expand Up @@ -46,7 +46,7 @@ The administrator session-revocation API and retained frontend show current Hub

The deployment-wide Copilot connection API and retained `/settings/copilot` frontend require a live administrator session. Hub obtains a credential from the configured provider and verifies it through the separate `replica-learning` process, then locks the persistent connection generation and rereads authority before committing the connection and typed security audit together. The database stores the provider key and configuration digest, never the credential.

The [learning foundation](learning-foundation.md) validates private storage, isolates the command's environment and temporary state, bounds output and execution time, and provides a PostgreSQL execution lock plus repository-store preparation primitive. Repository review collection, runs, decisions, and recall remain unimplemented because their product records and APIs do not exist.
The [learning foundation](learning-foundation.md) validates private storage, isolates the command's environment and temporary state, bounds output and execution time, and provides a PostgreSQL execution lock plus repository-store preparation primitive. The [review backend](review-collaboration.md) now provides complete repository snapshots with stable actors, deleted-message markers, and ordered resolution history. Learning import, runs, decisions, redaction execution, and recall remain unimplemented.

## Frontend

Expand Down
2 changes: 2 additions & 0 deletions hub/docs/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ Builds retain the author's provider, issuer, and provider user ID independently

Builds created before commit metadata was stored retain `NULL` for unknown values during the upgrade. A later detail API must represent missing values rather than inventing them. This migration does not import Rails records or map their integer IDs.

Review threads bind one non-removed repository, one reviewable prototype, and one successful Build. The root and replies keep stable Hub user UUIDs plus presentation snapshots. Soft deletion records when the author deleted a message but retains its source body; product reads and learning snapshots replace that body with `null`. Resolution events are immutable and uniquely ordered by their thread activity sequence, so resolve, reopen, and resolved-again transitions remain distinguishable for product reads and learning snapshots.

PostgreSQL `CHECK` expressions accept `NULL` unless the expression explicitly rejects it. Write nullable-branch checks so every invalid `NULL` combination evaluates to false. Design indexes from the real equality, range, ordering, and partial predicates used by lock, restore, and lookup queries.

Validate schema changes on both a fresh database and an upgrade from the exact base. Migration tests should seed representative base records and prove required data, backfills, relationships, and constraints after deployment. Do not enumerate the complete migration, table, column, or index inventory. Split PostgreSQL enum additions from statements that use the new values when transactional enum visibility requires a committed boundary.
Expand Down
8 changes: 4 additions & 4 deletions hub/docs/frontend.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Routed frontend

The Hub frontend uses React Router Framework Mode as a single-page application (SPA) rendered in the browser. In mock mode, it connects the retained pages to local product mocks. In real mode, the repository index, prototype details and Build history, administrator roster, and Hub-wide security audit use their production APIs. Creation and branching open the original Copilot app handoff.
The Hub frontend uses React Router Framework Mode as a single-page application (SPA) rendered in the browser. In mock mode, it connects the retained pages to local product mocks. In real mode, the repository index, prototype details and Build history, persisted review conversations, administrator roster, and Hub-wide security audit have production APIs. Creation and branching open the original Copilot app handoff.

This frontend does not restore the production Hub. Configured GitHub authentication, Hub admission, browser sessions, a repository index, and a prototype detail API are available; see [Authentication](authentication.md). The following remain separate backend work:

- Other product APIs and repository-specific permissions.
- Other product APIs and repository-specific permissions beyond the current live-member and non-removed-repository rule.
- External product integrations.
- Build hosting and publishing.

Expand Down Expand Up @@ -32,7 +32,7 @@ The dataset includes `octocat`, `mona`, additional fictional collaborators, `git

In mock mode, the neutral root reads the simulated session. Private pages load their workspace in a separate layout; public shared previews and signed-out pages do not load a private workspace. These provisional product contracts are not adapters for real authentication or authorization.

In real mode, signed-out visitors see the authentication shell without loading provisional session or workspace data. Signed-in members open the first repository or an empty workspace. Administrators can open `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` without loading provisional product workspace data. The sessions page reads current Hub authentication counts, requires explicit confirmation, leaves for fresh authorization through the current session provider, and keeps the signed-out completion result visible after the API ends every Hub session. Sign-in, enrollment, and sign-out forms submit natively to the configured API. Members can search the index, filter it by user, page through 24 prototypes at a time, and open prototype details and Build history. The detail API selects the latest successful Build by default; `build` pins another successful Build, and invalid or unavailable selections return 404. A member can edit the name, description, and start page of any visible prototype; saving a draft registers it. Later edits preserve its author and registration time. Sharing links remain unavailable in real mode. Users from other providers are shown by name or login without a GitHub link. Build user metadata may be unknown for older records. Hosted previews and live review remain unavailable, and other real product routes retain explicit API failures. In mock mode, `/` keeps the product entry flow, and `/admin-enrollment` redirects to the mock `/settings/enroll` flow. See [Hub development](development.md) for seed data and access limitations.
In real mode, signed-out visitors see the authentication shell without loading provisional session or workspace data. Signed-in members open the first repository or an empty workspace. Administrators can open `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` without loading provisional product workspace data. The sessions page reads current Hub authentication counts, requires explicit confirmation, leaves for fresh authorization through the current session provider, and keeps the signed-out completion result visible after the API ends every Hub session. Sign-in, enrollment, and sign-out forms submit natively to the configured API. Members can search the index, filter it by user, page through 24 prototypes at a time, and open prototype details and Build history. The detail API selects the latest successful Build by default; `build` pins another successful Build, and invalid or unavailable selections return 404. A member can edit the name, description, and start page of any visible prototype; saving a draft registers it. Later edits preserve its author and registration time. Sharing links remain unavailable in real mode. Users from other providers are shown by name or login without a GitHub link. Build user metadata may be unknown for older records. Hosted previews, retained review-UI wiring, and live review updates remain unavailable, and other real product routes retain explicit API failures. In mock mode, `/` keeps the product entry flow, and `/admin-enrollment` redirects to the mock `/settings/enroll` flow. See [Hub development](development.md) for seed data and access limitations.

The Build pickers and History list all Build states in both modes. Successful Builds open the prototype view with `?build=N`; other Builds are plain text because Hub does not store workflow run URLs. History shows when each Build was added to Hub in the viewer's local timezone and names that timezone. Real Builds have no hosted previews yet. The separate mock share-link picker offers only successful Builds with a preview and keeps selections on the share-links page.

Expand Down Expand Up @@ -205,7 +205,7 @@ These are frontend/mock contracts under [the application contracts](../client/ap
| `GET /api/settings/workspace`, `/api/settings/public`, `/api/settings/admin-candidates` | Settings records and synthetic page capabilities |
| `POST /api/settings/actions` | Explicitly named local actions; administrator role changes return 501 without changing state |

In real mode, Express implements `GET /api/workspace`, `GET /api/repositories/:repositoryId`, its `authors` endpoint, `GET /api/repositories/:repositoryId/prototypes/:prototypeId`, its `builds` endpoint, and the [prototype metadata](#prototype-metadata-edits) `PATCH` endpoint. The workspace lists the viewer and non-removed repositories. The repository index returns 24 eligible prototypes per page. It accepts `q`, `author`, and `page`, and rejects malformed values. Search ignores letter case and matches the prototype name, description, branch, and author login or name. A page past the end shows the last page. Each prototype includes its current Build or, when unset, the chronologically latest Build. The detail endpoint also includes unregistered prototypes and branches that were deleted, but excludes the default branch, replicas, and the reserved installation branch. It chooses the latest successful Build or a requested successful Build number; invalid and unavailable selections return 404. A user's first normal view of each prototype requests the information dialog; later views do not. Minimized views and HEAD requests do not consume the introduction. Unknown Build metadata remains null. Preview URLs and screenshots remain null because Hub does not host Builds yet. The authors endpoint lists other users with eligible prototypes, 20 at a time, sorted by login. Its cursor only marks where the last page ended. The [authentication guide](authentication.md) owns the real session routes.
In real mode, Express implements `GET /api/workspace`, `GET /api/repositories/:repositoryId`, its `authors` endpoint, `GET /api/repositories/:repositoryId/prototypes/:prototypeId`, its `builds` endpoint, the [prototype metadata](#prototype-metadata-edits) `PATCH` endpoint, and the authenticated [review-comment routes](review-collaboration.md#product-api). The workspace lists the viewer and non-removed repositories. The repository index returns 24 eligible prototypes per page. It accepts `q`, `author`, and `page`, and rejects malformed values. Search ignores letter case and matches the prototype name, description, branch, and author login or name. A page past the end shows the last page. Each prototype includes its current Build or, when unset, the chronologically latest Build. The detail endpoint also includes unregistered prototypes and branches that were deleted, but excludes the default branch, replicas, and the reserved installation branch. It chooses the latest successful Build or a requested successful Build number; invalid and unavailable selections return 404. A user's first normal view of each prototype requests the information dialog; later views do not. Minimized views and HEAD requests do not consume the introduction. Unknown Build metadata remains null. Preview URLs and screenshots remain null because Hub does not host Builds yet. The authors endpoint lists other users with eligible prototypes, 20 at a time, sorted by login. Its cursor only marks where the last page ended. The [authentication guide](authentication.md) owns the real session routes.

For example, `GET /api/repositories/:repositoryId/prototypes/:prototypeId/builds?page=2&build=1` returns older Builds while keeping successful Build 1 selected. History uses the same prototype visibility rules and rechecks the member's session before returning data. It accepts a positive `page` of up to nine digits and an optional positive `build` number. It returns 25 Builds per page newest first by workflow creation time (or Hub creation time when unavailable), and returns 404 for a page past the end. Equal times use descending Build number order. An empty history has one empty page.

Expand Down
12 changes: 6 additions & 6 deletions hub/docs/learning-foundation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Learning foundation

Hub can persist one deployment-wide Copilot connection and run the host-neutral [`replica-learning`](../../packages/learning/README.md) command through a bounded process boundary. Repository review collection, learning runs, decisions, recalls, and product records are not connected yet.
Hub can persist one deployment-wide Copilot connection and run the host-neutral [`replica-learning`](../../packages/learning/README.md) command through a bounded process boundary. The review backend can capture one complete repository snapshot, but learning imports, runs, decisions, redactions, and recalls are not connected yet.

The package remains the authority for consent, purpose, evidence, approval, redaction, and learning lifecycle rules. Hub does not reimplement those rules.

Expand All @@ -22,9 +22,9 @@ Disconnecting removes the connection record and advances the generation. It does

`REPLICA_LEARNING_ROOT` defaults to `storage/learning`. It must be a dedicated directory outside every configured static-file root. Hub rejects the filesystem root, the Hub application root, the shared `storage` root, the source public directory, the configured built-client directory and their descendants, files, and paths containing symbolic links. The check runs at startup and again when a repository store is prepared.

A future repository integration supplies a stable repository UUID and package scope such as `github.com/repositories/123`. The store primitive creates `<root>/repositories/<repository-uuid>` with mode `0700` and writes the package's default `config.json` with mode `0600` only when it is absent. Existing configuration remains operator-owned.
A future repository learning integration supplies the persisted repository UUID and package scope such as `github.com/repositories/123`. The store primitive creates `<root>/repositories/<repository-uuid>` with mode `0700` and writes the package's default `config.json` with mode `0600` only when it is absent. Existing configuration remains operator-owned.

Hub has no repository product model on the current branch, so it does not create stores or invoke repository commands yet.
Hub does not create stores or invoke repository learning commands yet.

## Command boundary

Expand Down Expand Up @@ -56,12 +56,12 @@ The environment-token mode may obtain its secret through a platform secret refer

## Remaining integration seam

Repository learning runs remain blocked on real repository, Build, prototype, review-thread, and review-comment APIs. Once those product domains exist, they can:
Repository learning runs can consume `captureRepositoryReviewSnapshot()` from the [review backend](review-collaboration.md#learning-snapshot-seam). A future orchestration layer can:

1. Authorize the repository operation.
2. Derive a stable package scope and prepare its store.
3. Acquire the learning execution lock.
4. Capture the complete review snapshot.
4. Capture the complete repeatable-read review snapshot.
5. Invoke package import, labeling, consolidation, decision, redaction, or recall commands.

That integration must keep the package's consent and lifecycle rules intact.
That integration must keep the package's consent and lifecycle rules intact. It must not create another Hub review store or omit deleted-message and resolution-history records from the imported snapshot.
Loading
Loading