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
2 changes: 1 addition & 1 deletion hub/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Hub is being rebuilt in TypeScript. Read the [root instructions](../AGENTS.md),
- [Development](docs/development.md) and [testing](docs/testing-and-operations.md) own local and CI commands.
- [Storybook](docs/storybook.md#ui-changes-and-pull-request-evidence) owns presentation coverage, cleanup, and PR screenshots.

Run Node commands from `hub/`, locally or inside the devcontainer. PostgreSQL and Prisma support configured GitHub authentication, administrator enrollment, Hub sessions, and a seeded read-only prototype index; see [authentication](docs/authentication.md). Other prototype APIs and repository-specific permissions are not built. Agree on the design before adding more product models, permissions, deployment choices, or product API routes.
Run Node commands from `hub/`, locally or inside the devcontainer. PostgreSQL and Prisma support configured GitHub authentication, administrator enrollment, Hub sessions, and a seeded prototype index with registered prototype name editing through the API; see [authentication](docs/authentication.md). Other prototype APIs and repository-specific permissions are not built. Agree on the design before adding more product models, permissions, deployment choices, or product API routes.

Use `npm run dev:api` to run Hub with local developer sign-in; this is the default choice for trying or testing Hub. Use `npm run dev:api:live` only when the task needs real GitHub or Entra sign-in configured in `.env`. [Development](docs/development.md#start-with-the-real-api) explains both modes.

Expand Down
10 changes: 6 additions & 4 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 and prototype details. 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 read access to the seeded repository index and prototype details, plus registered prototype name edits. 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, read-only repository index. The app cannot yet discover real repositories, import Builds, host published previews, edit product data, 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 a seeded repository index and edit registered prototype names through the API. The app cannot yet discover real repositories, import Builds, host published previews, or support live multi-user reviews.

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.

Expand All @@ -20,7 +20,9 @@ API code lives under `server/`. As features are added, route handlers will read

The [database guide](database.md) defines the multi-file Prisma schema and shared client in integrations. The health route remains a process check, not a database readiness check.

The [Pino integration](logging.md) writes structured application and HTTP logs to stdout. `createApp()` installs request logging before routes, so new endpoints inherit completion records and server-generated request IDs without explicit logging calls. Authentication routes install their bounded form parsing after origin and rate-limit checks; other routes inherit the shared JSON parser.
The [Pino integration](logging.md) writes structured application and HTTP logs to stdout. `createApp()` installs request logging before routes, so new endpoints inherit completion records and server-generated request IDs without explicit logging calls. Authentication routes install their bounded form parsing after origin and rate-limit checks. Prototype edits check the application origin before bounded JSON parsing, including case and trailing-slash aliases; other routes inherit the shared JSON parser.

The [prototype name-edit API](frontend.md#registered-prototype-name-edits) lets signed-in members rename visible registered prototypes. Hub holds session authority and prototype visibility locks through the write and detail read-back. The frontend editor and draft registration remain separate work.

The [background-job foundation](background-jobs.md) uses BullMQ with PostgreSQL and separate on-demand and scheduled worker processes. Setup migrates BullMQ's own schema independently of Prisma. Product processors and schedules are not registered yet.

Expand Down Expand Up @@ -63,7 +65,7 @@ Imports follow the arrows above. Shared components, hooks, and utilities must no

The theme provider wraps routes and their loading and error feedback.

- In real mode, signed-out visitors use the authentication shell. Signed-in members can browse the read-only repository index and open prototype details. Administrators can use `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` through their production APIs without loading provisional product data.
- In real mode, signed-out visitors use the authentication shell. Signed-in members can browse the repository index and open prototype details; the detail editor is not shown yet. Administrators can use `/settings/administrators`, `/settings/sessions`, `/settings/copilot`, and `/settings/audit?scope=hub` through their production APIs without loading provisional product data.
- In mock mode, the root reads the simulated session. A nested layout loads the private workspace for signed-in pages.
- Route loaders and actions request product data and refresh it after changes. Shareable filters and selections live in the URL.
- Product screens keep product-facing copy. API failures remain visible errors.
Expand Down
2 changes: 2 additions & 0 deletions hub/docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ The migration owns the single global revocation row. Its identity and history ar

Restoration reads the current revision, locks active provider rows in key order, then share-locks the global revocation row and rechecks the revision before locking membership, assignments, and the session. It checks the revision again before returning authority. Administrator continuation, Copilot changes, and ending all Hub sessions lock provider rows in key order, then lock the global revocation row exclusively before changing state. This serializes mutations with restoration even when bootstrap or administrator authority has no provider row to lock. Those mutations can briefly block restoration and admission.

Prototype name edits share-lock provider rows in key order and then share-lock the global revocation row before restoring session authority and locking prototype visibility. They keep those locks through the write and detail read-back. Shared provider locks allow sign-in and session restoration to proceed concurrently; provider reconciliation waits for the edit, and the revocation lock can delay global sign-out.

`GET /api/auth/session` restores the current session and returns its current role plus the membership's provider-neutral presentation identity. `POST /api/auth/session/sign-out` ends it and clears the cookie. Hub does not issue refresh tokens, perform provider logout, or support step-up authentication.

## HTTP boundary
Expand Down
Loading
Loading