# kapishdima/remocn architecture

> Architecture diagram of the GitHub repository kapishdima/remocn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kapishdima/remocn
- Repository: https://github.com/kapishdima/remocn

## Overview

1. **Repository shape**
This is a single Next.js application that serves three main products from one codebase: the marketing/docs site, the shadcn-style component registry, and a server-side video render API for the interactive “stars” tool.

2. **Primary user-facing surfaces**
The app routes under `app/(home)` provide the public site: homepage, sponsors page, and the `/stars` generator. The `app/docs` route is the documentation experience. These are separate route groups, but they share the same underlying component system and site configuration.

3. **Docs system**
Documentation content lives in `content/docs` as MDX, organized by category such as compositions, UI blocks, transitions, typography, and environment. `app/docs/[[...slug]]` renders those docs, and the `components/docs` folder supplies the docs shell, cards, previews, command blocks, and tabbed layouts used by the Fumadocs-powered site.

4. **Registry as the distribution boundary**
The actual copy-paste library is expressed in `registry/`. There are two main registry families: `registry/remocn-ui` for reusable UI primitives and transitions, and `registry/remocn` for higher-level scenes and compositional animations. Each package has its own `index.tsx` and `config.ts`, with some entries also shipping previews and tests.

5. **Published registry artifacts**
The `public/r/*.json` files are the generated registry payloads consumed by `shadcn add @remocn/...`. This is the external contract of the repo: consumers do not import from the app directly; they pull registry JSON that resolves to code copied into their own project.

6. **Remotion integration layer**
`src/remotion` contains the Remotion entry points (`Root.tsx`, demo roots, and demo entry wiring). This is the animation/runtime boundary for anything that renders video scenes, previews, or compositions. The repository’s registry components are written to be copied into Remotion projects, not used as a runtime package dependency.

7. **The `/stars` live generator**
`app/(home)/stars` is a client-heavy experience that lets a user enter a GitHub repo, customize output, preview the result, and export MP4. The hooks under `app/(home)/stars/hooks` manage the tool state: fetching stargazers, controlling the player, orientation, generation progress, and export.

8. **Server-side MP4 render pipeline**
The `/api/render` endpoints implement asynchronous video rendering. The route accepts jobs, tracks status by `jobId`, and exposes a download endpoint once the render completes. Under `lib/server`, the render flow is split into validation, queueing, bundling, path management, cleanup, and rate limiting.

9. **External data dependencies**
The app integrates with GitHub for repo parsing and stargazer data. `lib/github.ts` and `lib/github-stargazers.ts` are the main integration points, while `/api/search` and `/api/stargazers` expose that data to the UI. These endpoints feed the “stars” workflow and likely the landing-page social proof sections.

10. **Design system and shared UI**
`components/ui` is a large internal component library built from shadcn/Radix-style primitives, extended with custom controls like charts, sliders, dialogs, sidebars, and toasts. Higher-level reusable visuals such as Aurora, Dither, Silk, shimmering text, and spotlight surfaces live at the top level in `components/`.

11. **Site composition and theming**
`app/layout.tsx`, `app/globals.css`, `config/site.ts`, and utilities in `lib/layout.shared.tsx` establish the global shell, metadata, and shared presentation rules. Theme toggling and responsive behavior are handled through small hooks/components in `app/(home)/components` and `hooks/`.

12. **Build and deployment constraints**
The repo is built with Bun, Biome, and Tailwind CSS 4. Deployment is sensitive to Remotion’s headless Chromium requirements: the README and tooling split the render deployment into Nixpacks or Dockerfile paths, with scripts such as `bundle-remotion.mts`, `ensure-browser.mts`, and `render-demos.mts` supporting prebundling and render readiness.

13. **What to draw in an architecture diagram**
A good diagram would show: users entering the Next.js app; content flowing from MDX and registry definitions into docs pages and generated registry JSON; the `/stars` UI calling GitHub-backed API routes; and the server render API invoking Remotion/headless Chromium to produce downloadable MP4s. The key boundary is that registry consumers copy code out of the repo, while the live app uses the same primitives to present docs, demos, and video generation.

Main entry points: [`app/layout.tsx`](https://github.com/kapishdima/remocn/blob/main/app/layout.tsx) (App shell), [`app/(home)/stars/page.tsx`](https://github.com/kapishdima/remocn/blob/main/app/(home)/stars/page.tsx) (Stars tool), [`registry/remocn-ui`](https://github.com/kapishdima/remocn/tree/main/registry/remocn-ui) (UI registry), [`registry/remocn`](https://github.com/kapishdima/remocn/tree/main/registry/remocn) (Scene registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_app_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_home_site["Home site<br/>route group<br/>[page.tsx]"]
  node_sponsors_page["Sponsors<br/>route page<br/>[page.tsx]"]
  node_stars_tool["Stars tool<br/>client route<br/>[page.tsx]"]
  node_stars_hooks["Stars hooks<br/>tool state"]
end

subgraph group_docs["Docs system"]
  node_docs_page["Docs page<br/>docs route<br/>[page.tsx]"]
  node_docs_content["MDX content<br/>docs content"]
  node_docs_components["Docs UI<br/>docs components"]
end

subgraph group_registry["Registry"]
  node_registry_root["Registry index<br/>registry manifest<br/>[__index__.tsx]"]
  node_registry_ui["UI registry<br/>registry family"]
  node_registry_scenes["Scene registry<br/>registry family"]
  node_published_payloads["Registry JSON<br/>published artifacts<br/>[registry.json]"]
end

subgraph group_runtime["Remotion runtime"]
  node_remotion_root["Remotion root<br/>composition root<br/>[Root.tsx]"]
end

subgraph group_server["Render backend"]
  node_stars_api["Stars APIs<br/>api routes<br/>[route.ts]"]
  node_render_api["Render API<br/>async job api<br/>[route.ts]"]
  node_server_flow["Render flow<br/>server pipeline"]
  node_github_integration["GitHub data<br/>integration<br/>[github.ts]"]
end

subgraph group_shared["Shared UI"]
  node_site_config["Site config<br/>[site.ts]"]
  node_shared_ui["UI library<br/>design system"]
  node_visuals["Site visuals<br/>presentation"]
end

subgraph group_tooling["Tooling"]
  node_build_scripts["Build scripts<br/>tooling scripts"]
end

node_app_layout -->|"hosts"| node_home_site
node_app_layout -->|"hosts"| node_docs_page
node_app_layout -->|"hosts"| node_stars_tool
node_site_config -->|"metadata"| node_app_layout
node_docs_content -->|"content"| node_docs_page
node_docs_components -->|"renders"| node_docs_page
node_shared_ui -->|"primitives"| node_docs_components
node_visuals -->|"decorates"| node_home_site
node_shared_ui -->|"foundation"| node_visuals
node_stars_tool -->|"state"| node_stars_hooks
node_stars_hooks -->|"fetches"| node_stars_api
node_stars_api -->|"reads"| node_github_integration
node_render_api -->|"orchestrates"| node_server_flow
node_server_flow -->|"bundles"| node_remotion_root
node_remotion_root -->|"prepares"| node_build_scripts
node_registry_root -->|"indexes"| node_registry_ui
node_registry_root -->|"indexes"| node_registry_scenes
node_registry_ui -->|"publishes"| node_published_payloads
node_registry_scenes -->|"publishes"| node_published_payloads
node_registry_scenes -->|"targets"| node_remotion_root
node_registry_ui -->|"showcased in"| node_docs_components
node_stars_tool -->|"exports"| node_render_api

click node_app_layout "https://github.com/kapishdima/remocn/blob/main/app/layout.tsx"
click node_home_site "https://github.com/kapishdima/remocn/blob/main/app/(home)/page.tsx"
click node_sponsors_page "https://github.com/kapishdima/remocn/blob/main/app/(home)/sponsors/page.tsx"
click node_stars_tool "https://github.com/kapishdima/remocn/blob/main/app/(home)/stars/page.tsx"
click node_docs_page "https://github.com/kapishdima/remocn/blob/main/app/docs/[[...slug]]/page.tsx"
click node_docs_content "https://github.com/kapishdima/remocn/tree/main/content/docs"
click node_docs_components "https://github.com/kapishdima/remocn/tree/main/components/docs"
click node_site_config "https://github.com/kapishdima/remocn/blob/main/config/site.ts"
click node_shared_ui "https://github.com/kapishdima/remocn/tree/main/components/ui"
click node_visuals "https://github.com/kapishdima/remocn/tree/main/components"
click node_stars_hooks "https://github.com/kapishdima/remocn/tree/main/app/(home)/stars/hooks"
click node_stars_api "https://github.com/kapishdima/remocn/blob/main/app/api/search/route.ts"
click node_render_api "https://github.com/kapishdima/remocn/blob/main/app/api/render/route.ts"
click node_server_flow "https://github.com/kapishdima/remocn/tree/main/lib/server"
click node_github_integration "https://github.com/kapishdima/remocn/blob/main/lib/github.ts"
click node_registry_root "https://github.com/kapishdima/remocn/blob/main/registry/__index__.tsx"
click node_registry_ui "https://github.com/kapishdima/remocn/tree/main/registry/remocn-ui"
click node_registry_scenes "https://github.com/kapishdima/remocn/tree/main/registry/remocn"
click node_published_payloads "https://github.com/kapishdima/remocn/blob/main/public/r/registry.json"
click node_remotion_root "https://github.com/kapishdima/remocn/blob/main/src/remotion/Root.tsx"
click node_build_scripts "https://github.com/kapishdima/remocn/blob/main/scripts/bundle-remotion.mts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_home_site,node_sponsors_page,node_stars_tool,node_stars_hooks,node_build_scripts toneBlue
class node_docs_page,node_docs_content,node_docs_components toneAmber
class node_registry_root,node_registry_ui,node_registry_scenes,node_published_payloads toneMint
class node_remotion_root toneRose
class node_stars_api,node_render_api,node_server_flow,node_github_integration toneIndigo
class node_site_config,node_shared_ui,node_visuals toneTeal
```

## Components

### Next.js app

Public site, docs, and live stars tool routes.

- [App shell](https://github.com/kapishdima/remocn/blob/main/app/layout.tsx): next layout · Global app layout and metadata shell. · `app/layout.tsx`
- [Home site](https://github.com/kapishdima/remocn/blob/main/app/(home)/page.tsx): route group · Marketing homepage and shared public surfaces. · `app/(home)/page.tsx`
- [Sponsors](https://github.com/kapishdima/remocn/blob/main/app/(home)/sponsors/page.tsx): route page · Sponsor landing page within the public site. · `app/(home)/sponsors/page.tsx`
- [Stars tool](https://github.com/kapishdima/remocn/blob/main/app/(home)/stars/page.tsx): client route · Interactive GitHub repo to MP4 generator. · `app/(home)/stars/page.tsx`
- [Stars hooks](https://github.com/kapishdima/remocn/tree/main/app/(home)/stars/hooks): tool state · Client state, stargazer fetching, orientation, export, and player control. · `app/(home)/stars/hooks`

### Docs system

MDX content and docs-specific UI.

- [Docs page](https://github.com/kapishdima/remocn/blob/main/app/docs/[[...slug]]/page.tsx): docs route · Fumadocs-powered docs renderer. · `app/docs/[[...slug]]/page.tsx`
- [MDX content](https://github.com/kapishdima/remocn/tree/main/content/docs): docs content · Structured documentation source for site sections. · `content/docs`
- [Docs UI](https://github.com/kapishdima/remocn/tree/main/components/docs): docs components · Shells, previews, cards, tabs, and command blocks for docs. · `components/docs`

### Registry

Copy-paste component distribution boundary.

- [Registry index](https://github.com/kapishdima/remocn/blob/main/registry/__index__.tsx): registry manifest · Top-level registry catalog and package boundary. · `registry/__index__.tsx`
- [UI registry](https://github.com/kapishdima/remocn/tree/main/registry/remocn-ui): registry family · Reusable UI primitives, transitions, and controls for copy-paste use. · `registry/remocn-ui`
- [Scene registry](https://github.com/kapishdima/remocn/tree/main/registry/remocn): registry family · Higher-level compositions, animations, and scene presets. · `registry/remocn`
- [Registry JSON](https://github.com/kapishdima/remocn/blob/main/public/r/registry.json): published artifacts · External shadcn add payloads consumed by downstream projects. · `public/r/registry.json`

### Remotion runtime

Video rendering entry points and demo wiring.

- [Remotion root](https://github.com/kapishdima/remocn/blob/main/src/remotion/Root.tsx): composition root · Remotion entry points and demo wiring boundary. · `src/remotion/Root.tsx`

### Render backend

API routes and server-side render pipeline.

- [Stars APIs](https://github.com/kapishdima/remocn/blob/main/app/api/search/route.ts): api routes · Search and stargazer endpoints consumed by the stars workflow. · `app/api/search/route.ts`
- [Render API](https://github.com/kapishdima/remocn/blob/main/app/api/render/route.ts): async job api · Job submission, status tracking, and download endpoints for MP4 rendering. · `app/api/render/route.ts`
- [Render flow](https://github.com/kapishdima/remocn/tree/main/lib/server): server pipeline · Validation, queueing, bundling, cleanup, paths, and rate limiting. · `lib/server`
- [GitHub data](https://github.com/kapishdima/remocn/blob/main/lib/github.ts): integration · Repo parsing and stargazer data access layer. · `lib/github.ts`

### Shared UI

Reusable site components and design primitives.

- [Site config](https://github.com/kapishdima/remocn/blob/main/config/site.ts): config · Global site metadata and navigation configuration. · `config/site.ts`
- [UI library](https://github.com/kapishdima/remocn/tree/main/components/ui): design system · Internal shadcn/Radix-style primitives and controls. · `components/ui`
- [Site visuals](https://github.com/kapishdima/remocn/tree/main/components): presentation · Custom high-level visual surfaces used across the app. · `components`

### Tooling

Scripts and deployment/runtime support.

- [Build scripts](https://github.com/kapishdima/remocn/blob/main/scripts/bundle-remotion.mts): tooling scripts · Bundling, browser readiness, and demo render support scripts. · `scripts/bundle-remotion.mts`

## Connections

- App shell → Home site: hosts · The global shell renders the public site routes.
- App shell → Docs page: hosts · The app shell also wraps the docs experience.
- App shell → Stars tool: hosts · The same shell wraps the interactive stars generator.
- Site config → App shell: metadata · Site metadata and navigation feed the app shell.
- MDX content → Docs page: content · MDX content is rendered into the docs route.
- Docs UI → Docs page: renders · Docs-specific shells and blocks compose the page.
- UI library → Docs UI: primitives · Docs UI is built on top of shared design primitives.
- Site visuals → Home site: decorates · Custom presentation components power landing sections.
- UI library → Site visuals: foundation · Higher-level visuals use the shared UI layer underneath.
- Stars tool → Stars hooks: state · The generator screen delegates most behavior to hooks.
- Stars hooks → Stars APIs: fetches · Client state pulls stargazer and search data from APIs.
- Stars APIs → GitHub data: reads · API routes rely on GitHub parsing and stargazer helpers.
- Render API → Render flow: orchestrates · Render endpoints drive the async server pipeline.
- Render flow → Remotion root: bundles · The server pipeline prepares Remotion compositions for rendering.
- Remotion root → Build scripts: prepares · Remotion entry points are supported by build and bundling scripts.
- Registry index → UI registry: indexes · The root registry catalog includes the UI family.
- Registry index → Scene registry: indexes · The root registry catalog includes the scene family.
- UI registry → Registry JSON: publishes · UI registry packages are emitted as external JSON payloads.
- Scene registry → Registry JSON: publishes · Scene registry packages are also emitted as registry JSON.
- Scene registry → Remotion root: targets · Scene packages are authored for Remotion projects and runtime.
- UI registry → Docs UI: showcased in · Docs examples and previews present registry primitives.
- Stars tool → Render API: exports · The live generator submits render jobs to the backend.