kapishdima/remocn

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.