Technical setup
This repository is a pnpm workspace managed by Turborepo. It builds two surfaces from the same source: the Nextra documentation site and the shadcn-compatible JSON consumed by Circle Health applications.
One workspace builds the catalog and the files it documents.
Package versions below come directly from the workspace manifests. The lockfile fixes the resolved dependency graph.
System boundary
The Registry distributes source, not a runtime UI package. @circle/ui is the
private authoring package inside this workspace. Consumers use the
shadcn CLI, receive files in their own source
tree, and own those files from then on.
| Boundary | Responsibility |
|---|---|
| Authoring | React modules, CSS tokens, localized copy, skills, and item metadata. |
| Registry | Import rewriting, dependency discovery, targets, and item manifests. |
| Documentation | Catalog navigation, previews, usage, sample data, and public payloads. |
| Consumer | Installed source, application integration, and later local changes. |
Build pipeline
packages · skills · configregistry/berlin · generatedapps/docs/publicshadcn writes into the app1. Author
The durable sources are:
packages/ui/srcfor components, blocks, utilities, types, and localized copypackages/styles/src/globals.cssfor base CSS variables and typographyskillsfor installable agent workflowsconfig/registry/items.jsonfor item metadata and target overridesconfig/registry/styles.jsonfor theme variantsconfig/registry/site.jsonfor namespaces, aliases, and the public hostconfig/docs/registry.jsonfor catalog grouping and navigation
Every root component must have one explicit registry item. An entry exported
from packages/ui/src/index.ts can also receive a live documentation preview.
2. Compile
pnpm registry:sync runs scripts/registry/build.mjs. The script:
- reads authored source and registry configuration;
- maps each source module to one registry item;
- rewrites local imports to namespaced registry paths;
- derives npm and registry dependencies from imports;
- writes transformed source to
registry/berlin; and - writes manifests and catalog metadata to
config/registry/generatedandregistry.json.
Explicit dependencies and file targets in items.json supplement values that
cannot be derived from imports.
3. Publish
pnpm registry:build performs the registry sync, then runs shadcn build once
per namespace. The resulting JSON is written below apps/docs/public:
/circle-ui/{name}.json
/blocks/{name}.json
/utilities/{name}.json
/i18n/{name}.json
/skills/{name}.jsonThe documentation application and these static payloads are served from
registry.circle.health.
4. Generate documentation
pnpm docs:sync combines generated item metadata with docs configuration. It
produces catalog pages, sidebar maps, skill pages, the CircleOS PII-mask page,
and the rendered changelog.
Handwritten pages such as this one explain durable concepts. Item reference
pages are generated so their install commands and dependencies stay aligned
with the public payload. An item listed in its namespace’s authoredItems
configuration keeps its handwritten page while still using live
RegistryItem sections for installation and dependency data.
Workspace map
| Path | Owns |
|---|---|
packages/ui | Installable React and TypeScript source. |
packages/styles | Base CSS and Circle Health design tokens. |
config/registry | Registry definitions plus generated manifests. |
config/docs | Catalog information architecture. |
registry/berlin | Transformed source passed to the shadcn builder. |
apps/docs/content | Handwritten and generated Nextra MDX. |
apps/docs/public | Public registry JSON, fonts, brand assets, and synthetic data. |
scripts/registry | Registry compilation and public-payload builds. |
scripts/docs | Documentation synchronization. |
scripts/sample-data | Synthetic lab-report and intake-form generation. |
Documentation runtime
The docs app uses the Next.js App Router with
Nextra. The catch-all route at
apps/docs/app/[[...mdxPath]]/page.tsx imports pages from apps/docs/content.
apps/docs/content/_meta.tsx owns the top-level navigation.
The docs package runs registry and docs generation in both predev and
prebuild. A local or production Next.js build therefore uses current
generated artifacts instead of whatever happened to be on disk beforehand.
The root layout marks the site noindex, nofollow, and noarchive. That is a
crawler policy, not access control.
Generated boundaries
Change the source on the left, then regenerate the output on the right.
| Source of truth | Generated output |
|---|---|
packages/ui, packages/styles, skills | registry/berlin |
config/registry/*.json and authored source | config/registry/generated, registry.json |
| Generated namespace manifests | Registry JSON under apps/docs/public |
Generated item metadata + config/docs | Component, block, utility, and skill catalog pages |
CHANGELOG.md | apps/docs/content/changelog.mdx |
scripts/circle-os/pii-mask.js | apps/docs/content/utilities/pii-mask.mdx |
scripts/sample-data configuration and sources | PDFs and manifests under apps/docs/public/sample-data |
Do not hand-edit generated output. The relevant build removes and recreates managed directories.
Local workflow
Start the docs application:
pnpm install
pnpm dev:docsAfter changing registry source or configuration:
pnpm registry:build
pnpm docs:sync
pnpm typecheck
pnpm buildpnpm build is the production gate. Turborepo type-checks the private UI
package, rebuilds registry and docs artifacts through the docs package hooks,
and runs the Next.js production build.
Failure modes
- An unconfigured root component stops the registry build.
- A catalogued item missing from
config/docs/registry.jsonstops docs sync. - An
authoredItemsentry without its handwritten page stops docs sync. - Hand edits below generated paths are overwritten on the next build.
- Reinstalling a registry item in a consumer may replace its local changes; inspect the consumer diff before accepting an update.
- The generated JSON is committed. Unexpected payload changes should be investigated before merge, not hidden from the diff.