github-clone
PublicOpen-source GitHub clone: git repos, pull requests, issues, wiki, AI workspace, CLI and MCP. MIT.
Harakumo1 commitUpdated 2 downloads
Loading the files…
Nucleus is one long-running Next.js 16 server. It serves the web pages and a JSON API from the same process, keeps accounts and collaboration data in MongoDB, and keeps every repository as a real git repository on the server's own disk. An S3-compatible bucket, if configured, holds a snapshot of each repository so a wiped disk can be restored. A command-line client and an MCP server talk to the same API with a bearer token.
There is no job queue, no websocket or other realtime channel, and no payment system. Work that should not block a request (backups, AI action runs, notification email) runs as an in-process promise after the response is sent.
| Part | Where | What it does |
|---|---|---|
| Pages | src/app/**/page.tsx | Client-rendered React pages. They fetch JSON from the API routes below. |
| API routes | src/app/api/**/route.ts | Next.js route handlers. Every repository route resolves access through repoAccess(). |
| Authorization | src/lib/authz.ts | Finds the caller (session cookie or bearer token), loads the repository, applies read / contribute / write / admin rules, and restores the repository from its snapshot if it is missing from disk. |
| Sign-in | src/lib/auth.ts, src/lib/jwt.ts, src/lib/tokenversion.ts | NextAuth v5 with a username + password credentials provider and JWT sessions. CLI and MCP clients use a separate 30-day JWT. |
| Git storage | src/lib/git.ts, src/lib/safepush.ts, src/lib/diff.ts, src/lib/repofile.ts | Reads and writes repositories with isomorphic-git (pure JavaScript, no git binary needed). Three-way merge for pushes, LCS diffs and merges for pull requests, binary-safe file encoding. |
| Write locks | src/lib/locks.ts | In-memory, per-repository queue so two writes to the same repository never interleave. |
| Rate limits and quotas | src/lib/ratelimit.ts, src/lib/quota.ts | In-memory counters per user or per client IP; size caps on pushes. |
| AI | src/lib/ai.ts, src/lib/actions/engine.ts | runAI() is the only caller of a model provider. Claude (Anthropic) or Grok (xAI), chosen per request. |
src/lib/mail.ts, src/lib/email-templates.ts, src/lib/otp.ts | One HTTP call to Harakumo Mail for verification codes, password-reset codes and the "password changed" notice. | |
| Secrets | src/lib/crypto.ts | AES-256-GCM encryption of per-repository secrets with SECRETS_ENCRYPTION_KEY. |
| Backups | src/lib/storage/backup.ts, src/lib/storage/hydrate.ts, scripts/backup-all-repos.mjs | Tar + gzip snapshot of a repository to the bucket after each write; restore on first use when the files are missing. |
| Container previews | src/lib/preview/docker-manager.ts | Starts a short-lived Docker container for Python, Ruby, Go, Java, Rust, PHP and Flutter projects, only when a Docker socket is reachable. |
| Startup check | src/instrumentation.ts | Refuses to boot in production without MONGODB_URI, AUTH_SECRET and SECRETS_ENCRYPTION_KEY. |
| Data models | src/models/*.ts | Mongoose schemas. See docs/SYSTEM-DESIGN.md for every field. |
| CLI | cli/bin/nucleus.js, cli/commands/*.js, cli/lib/common.js | nucleus login / init / push / pull / sync / clone / list / status / logout. |
| MCP server | cli/mcp/server.mjs | stdio MCP server with seven tools that call the same HTTP API as the CLI. |
| Route | File | Purpose |
|---|---|---|
/ | src/app/page.tsx | Landing page |
/login, /register, /forgot-password | src/app/(auth)/ | Sign in, sign up, reset a password with an emailed code |
/dashboard, /explore, /new-org, /settings | src/app/(dashboard)/ | Your repositories, public repositories and search, create an organization, profile settings |
/new | src/app/new/page.tsx | Create a repository |
/chat | src/app/chat/page.tsx | AI workspace: chat, file tree, code editor, save into a repository |
/[username] | src/app/[username]/page.tsx | Profile, repositories, follow |
/[username]/[repo] | src/app/[username]/[repo]/page.tsx | Repository home with README, architecture analysis, AI chat, stats, preview, secrets and presentation tabs |
/[username]/[repo]/tree/..., /blob/..., /commits | src/app/[username]/[repo]/ | File browser, file view, history |
/[username]/[repo]/issues, /pulls, /discussions, /wiki, /projects | same | Collaboration features |
/[username]/[repo]/actions, /agents | same | AI actions and the AI agent team |
/[username]/[repo]/insights, /security, /settings | same | Commit charts, .env and SECURITY.md checks, visibility and collaborators |
/preview/[username]/[repo] | src/app/(standalone)/preview/ | Full-page live preview |
/orgs/[slug] and /people, /repositories, /settings | src/app/orgs/[slug]/ | Organization pages. /insights, /packages, /projects, /security and /teams show a "coming soon" placeholder. |
/contact, /privacy, /terms | src/app/(legal)/ | Legal pages |
| Group | Routes |
|---|---|
| Auth | api/auth/[...nextauth] (NextAuth), api/auth/register, api/auth/otp, api/auth/password, api/auth/cli-token |
| Repositories | api/repos (list, create), api/repos/[owner]/[repo] (get, delete) |
| Repository content | tree, blob, files (read all / commit), upload (CLI push), commits, branches, compare, download, zip, serve/[...path] (raw files for static previews), stats, fork, star |
| Collaboration | issues, pulls, discussions, wiki, projects |
| Repository admin | settings (visibility, default branch, collaborators), secrets |
| AI | api/ai/chat, api/repos/[owner]/[repo]/architecture, api/repos/[owner]/[repo]/actions, api/agents/team, api/agents/run, api/agents/tasks, api/agents/comms, api/agents/activity, api/agents/marketplace |
| People | api/users/[username], api/users/[username]/follow, api/users/[username]/orgs, api/users/settings, api/orgs, api/orgs/[slug], api/search |
| Previews | api/preview/container |
| Operations | api/health (database reachable and repository directory writable) |
src/lib/db.ts).NUCLEUS_REPOS_DIR, default ./repos) holds one
directory per repository at <owner>/<repo>.git. Despite the suffix it is a
normal repository with a working tree: the file browser, previews and
downloads read the working tree, and commits are written with
isomorphic-git.STORAGE_*, optional) holds
repos/<owner>/<repo>.tar.gz, one snapshot per repository, overwritten on
each write.localStorage. They are not stored
on the server unless the user saves them into the repository.~/.nucleus/config.json
(file mode 600) and the linked repository plus last-synced commit in
.nucleus.json inside the project folder.AUTH_SECRET. No OAuth or social sign-in.nucleus login opens /api/auth/cli-token?port=N in the
browser; once signed in, the server redirects to http://127.0.0.1:N/callback
with a 30-day JWT. The token carries the account's tokenVersion, so a
password reset revokes every earlier token.None. Nucleus has no billing, plans or payment provider.
| Service | Used for | Required |
|---|---|---|
| MongoDB | All structured data | Yes |
| Anthropic API | Claude, for chat, architecture analysis, agents and actions | One of the two AI keys, for AI features |
| xAI API | Grok, same uses | One of the two AI keys, for AI features |
| Harakumo Mail | Verification and password-reset codes | Recommended (no key means no password recovery) |
| S3-compatible bucket | Repository snapshots | Recommended; required on hosts without a persistent volume |
| Docker daemon | Container previews | Optional |
| WebContainer | Runs package.json projects in the visitor's browser | Loaded client-side by @webcontainer/api |
nucleus push and nucleus sync both send the whole project folder to the
upload route. The server merges it with anything pushed since the client last
synced, so a teammate's work is not overwritten.
Every repository route calls repoAccess(), which restores a missing
repository from its snapshot before anything reads it. Concurrent requests for
the same repository share one restore.
/chat sends the conversation to api/ai/chat. The model answers with
===FILE: path=== blocks, which the server parses and returns as a file
list. The page shows them in an editor; Save commits the changed files
through POST api/repos/[owner]/[repo]/files.upload route instead.architecture reads up to about 50 KB of the repository's files and asks the
model for a Markdown architecture document.api/agents/*) are entries from a fixed catalog in
src/models/AgentDefinition.ts that a writer "hires" onto a repository.
Running one stores the tasks, messages and activity it produces in MongoDB.api/repos/[owner]/[repo]/actions) bind an agent to a trigger.
Web edits through the files route fire on_push, new issues fire
on_issue, and the Run button fires manual.See docs/SYSTEM-DESIGN.md for the step-by-step flows, the data model,
permissions, limits and known gaps.