Quick read · Product and codebase
ByteBin, in brief
ByteBin is a developer workspace for managing code projects, working with GitHub repositories, using AI to understand code and commits, and collaborating with other ByteBin users. The Next.js app is the user-facing entry point; Express services handle repository, AI, file, and email work; PostgreSQL, MongoDB, and Kafka each have separate roles.
Two repository workflows
byte CLI uploads to the Library; it does not push to GitHub.How a user works with ByteBin
- Create an account and open the dashboard.
- Create a Library project or connect GitHub and choose an authorized repository.
- Add Library files with the web app or CLI; in Git Control, browse GitHub files.
- Index code before asking repository questions. Use Commit Finder to search a repository’s changes.
- Ask Tlux to find an account, manage a Library project, or handle a connection request. Tlux confirms sensitive actions.
- Review AI edits before applying them, then push GitHub changes only when ready.
- Save a conversation explicitly if you want to continue it later.
What happens behind the screen
Next.js app
Pages, dashboard, authentication, protected API routes, PostgreSQL access, and GitHub integration.
API gateway
Routes push/update, code Q&A, commit search, and Library file requests to backend services.
AI and code service
Indexes code, retrieves relevant passages, processes code updates, and explains selected commits.
File service
Reads and writes Library file documents in MongoDB.
History worker
Consumes explicit save/delete events from Kafka and persists conversations to PostgreSQL.
Email service
Sends account welcome messages through Resend when configured.
Data and AI memory
PostgreSQL owns accounts, project metadata, permissions, notifications, saved conversations, and repository embeddings. MongoDB stores Library file documents. Kafka carries conversation-save events to a worker; it is not the permanent conversation store. With history saving off, no save event is published. Saved conversations and their summaries are stored in PostgreSQL and expire seven days after their last save.
Repository Q&A splits text files into overlapping chunks, embeds them with Gemini, retrieves the five most relevant passages by default, and sends them to the configured chat model as context. Tlux uses recent messages plus a rolling summary for long conversations. This is request context and saved app data, not permanent memory inside the model.
Use the CLI
cd /path/to/ByteBin/byte
npm install && npm link
# from the local project you want in the ByteBin Library
byte login
byte add .
byte push "Bytebin/my-project"Use byte update CODE-ID to update an existing Library project, byte whoami to check the CLI session, and byte logout to end it. The CLI skips common secret and generated files; check the staged project before pushing.
Start here · User walkthrough
How to use ByteBin
Sign in to ByteBin and use the dashboard sidebar to choose a workspace. The steps below walk through each main feature. The key choice at the start is whether your code belongs in the ByteBin Library or in a GitHub repository: they are separate workflows.
1. Start at Overview
Open the dashboard Overview to see your workspace summary, recent activity, projects, and connection requests. Use the sidebar to move between sections; the notification bell opens alerts.
Open this section2. Create a Library project
Open Library → New entry. Enter a project name and description; optionally add a sub-project name and description, then choose Create. Search the Library to find entries, expand a project to inspect it, and use its code ID for CLI commands. Confirm before deleting: deletion cannot be undone.
Open this section3. Upload code with the CLI
Install the local CLI once with npm install and npm link inside the byte folder. From your code folder, run byte login, byte add . (or name specific paths), then byte push CODE-ID. For an existing Library project, run byte update CODE-ID. Use byte whoami to check the session and byte logout when finished. This uploads to Library, not GitHub.
Read CLI details4. Work with GitHub
Open Git Control and connect GitHub by installing ByteBin’s GitHub App with access to the repositories you choose. Select an authorized repository and branch, open the workspace, inspect files, and ask its code assistant for help. Review a proposed change, apply it in the workspace, and use the push action only when you are ready to send it to GitHub.
Open this section5. Ask questions about code
Choose the Library or GitHub code workflow that contains your code. Index the repository before asking questions so ByteBin has searchable code context; re-index after important changes. Ask a focused question, review the answer and referenced context, and verify important details against the files.
Open this section6. Find the commit behind a change
Connect GitHub and grant access to the repository first. Open Commit finder, enter the repository and branch (for example, main), then ask a question such as “Where was the login flow implemented?” Review the matching commits and open their GitHub links to verify the result.
Open this section7. Use Tlux
Open AI Assistant, type a request, and press Send (or use voice input). Tlux can look up an account by merchant code, send a connection request, and create or delete Library projects and sub-projects. Review its confirmation prompt before an action is carried out. It does not push GitHub code or run arbitrary shell commands.
Open this section8. Continue a saved Tlux chat
Use New chat when you want a separate thread. Select Save history to keep the current conversation, then open History and select its title to continue later. Use the adjacent delete control to remove a saved conversation. Unsaved chats are not persisted through the history-save pipeline; saved chats are account-scoped and expire seven days after their last save.
Open this section9. Connect with another ByteBin user
Open Connections and enter the person’s merchant code, then select Search. Check the matched profile and choose the connection request action. Use the incoming/outgoing request lists to accept or reject requests, or disconnect an existing connection. Sharing and visibility controls apply to connected users.
Open this section10. Review activity and alerts
Open Activity from the sidebar or click the notification bell. Select an unread item to mark it read; use Mark all read to clear the unread state for all listed notifications.
Open this section11. Manage your account
Open Settings to edit the available profile preferences, set or change a password, and toggle the notification indicator for this browser. Account deletion is permanent and requires typing DELETE to confirm. Use Log out in the sidebar to end the session.
Open this sectionIf something is missing
01 · Product
What ByteBin is
ByteBin is a developer workspace for managing code projects, working with GitHub repositories, asking AI questions about code, searching commit history, and collaborating with other ByteBin accounts. Tlux is its action-taking assistant.
There are two different code paths that are easy to confuse: the Library stores ByteBin-managed project files, including files uploaded with the CLI; Git Control connects to GitHub and works against repositories granted to ByteBin’s GitHub App. The CLI pushes files into the ByteBin Library, not directly to GitHub.
Organize
Library projects, files, and sub-projects.
Understand
Repository Q&A and commit discovery.
Collaborate
Connections, visibility, and shared work.
02 · Navigation
Dashboard and workspace
The dashboard sidebar is the main navigation. Overview summarizes your projects, activity, and connection requests. Library opens ByteBin projects; Git Control opens GitHub repositories; Commit finder searches repository history; and AI Assistant opens Tlux.
Connections manages account relationships and requests. Activity shows notifications. Settings contains account preferences and security actions. The bell control opens notifications without leaving the current page.
On smaller screens, the sidebar becomes a bottom navigation strip. Page changes use the dashboard’s content transition while keeping the sidebar in place.
03 · ByteBin projects
Library, projects, and files
A Library project is a ByteBin-owned container with a stable project ID and a readable code ID such as Bytebin/project-name. A project can contain named sub-projects, whose IDs follow the form Bytebin/project-name/sub-project. The code ID is the identifier used by CLI push and update commands.
- Create a project from the Library, dashboard shortcut, or Tlux after confirming the action.
- Add or upload files, or use the CLI to stage and push a folder.
- Open the project to browse the file tree, review its files, and use code-aware assistance where indexing is available.
- Use sharing controls to manage visibility for accepted connections.
PostgreSQL stores project ownership, IDs, names, and sub-project metadata. MongoDB stores the repository file documents. Those stores share the PostgreSQL project UUID so the API can enforce ownership across both.
Library is not a GitHub mirror
04 · GitHub integration
GitHub and Git Control
Connect GitHub by installing ByteBin’s GitHub App and selecting the repositories that the installation may access. ByteBin records the installation and repository metadata, then uses installation credentials when it reads a repository tree, file, or commit.
In Git Control, choose an authorized repository, open a workspace, inspect files, and ask the repository assistant for an edit. Review the proposed changes in the workspace. Applying a proposal changes the workspace; pushing is a separate action that sends the changes to GitHub and records the resulting commit status.
Disconnecting the integration revokes the app installation from the connected GitHub account. A repository not granted in the installation is not available through Git Control.
05 · Repository intelligence
Code indexing and repository AI
Repository Q&A uses retrieval augmented generation (RAG). When a repository is indexed, ByteBin takes text files, splits their contents into overlapping chunks, asks Gemini for embeddings, then stores each chunk and embedding in PostgreSQL. Binary files containing NUL bytes are skipped.
When you ask a question, ByteBin embeds the question, calculates cosine similarity against that project’s indexed chunks, and selects the most relevant passages (five by default). The selected file paths and text are passed to the chat model as context. The answer can include the previous conversation messages supplied by the chat UI.
In Git Control, the AI edit flow uses repository files and a proposed change. It does not automatically push a change: review and push remain explicit steps.
Indexing must happen first
06 · Change discovery
Commit Finder
Commit Finder starts with commit data from an authorized GitHub repository. It ranks candidate commits using lexical matching (BM25) and, when embeddings are available, semantic similarity. The retrieval mode can combine those rankings; if semantic retrieval fails, the service falls back to lexical results.
Relevant commit messages and available file or diff summaries are sent to the configured chat model. The response is constrained to the retrieved commits and includes the commit IDs and links so you can verify the result on GitHub. Embeddings are cached in PostgreSQL by repository and commit SHA to avoid embedding the same history repeatedly.
07 · Tlux assistant
What Tlux can do
Tlux is an authenticated assistant that can use ByteBin tools. In the current implementation it can find an account by merchant code, send a connection request, create a Library project or sub-project, and delete one. It should ask before sending a connection request and before creating or deleting a project.
Tlux does not run arbitrary shell commands or write directly to a GitHub repository. For code questions, use the repository assistant; for GitHub changes, use Git Control and review the proposed edit. Tlux’s replies are formatted in Markdown and the UI keeps the active thread while you work.
The assistant uses the configured Groq chat model. If the model provider or required credentials are unavailable, an assistant request can fail; account, project, and connection actions also depend on ByteBin’s authenticated API and database.
08 · User-controlled persistence
Conversation memory and saved history
LLM memory here has two parts: working context is the recent conversation sent with the next request, and saved history is the durable conversation you explicitly choose to keep. Tlux also summarizes older turns so a long saved conversation can retain goals, decisions, and unresolved questions while sending a bounded recent transcript to the model.
If saving is off, the history save endpoint does not publish a save event. When saving is on, the API confirms only after Kafka acknowledges the event; the worker validates it, retries transient database errors, and upserts the conversation. Saved assistant conversations keep their messages and summary in PostgreSQL and expire seven days after the most recent save. The conversation list is scoped to the signed-in account.
This is application memory, not model training or an unlimited permanent memory. The summary and recent messages are context for later requests; they do not change the model itself. Deleting a saved conversation queues a delete event through the same Kafka topic.
09 · Developer tool
Use the byte command line tool
The byte CLI lets a developer send local text files to a ByteBin Library project. It stages a list of files under the project’s .byte/ folder, then authenticates and sends those files through the gateway’s push or update endpoint.
For a local checkout, link the CLI package once:
cd /path/to/ByteBin/byte
npm install
npm linkThen, from the project folder you want to upload:
byte login
byte whoami
byte add .
byte push "Bytebin/my-project"Useful commands:
| Command | What it does |
|---|---|
| byte login | Signs in and stores a CLI session. |
| byte add . | Stages readable project files recursively. |
| byte add src/file.ts | Stages only the selected paths. |
| byte push CODE-ID | Creates or pushes staged files to a Library project. |
| byte update CODE-ID | Updates the existing project or sub-project. |
| byte whoami | Shows the active CLI account/session status. |
| byte logout | Revokes and removes saved CLI credentials. |
The CLI skips hidden directories, node_modules, build outputs, environment files, private keys, and other generated files. A file over 10 MB stops the staging operation. Review the staged project before pushing if it contains private or generated content.
Credentials are stored with restrictive file permissions in ~/.bytebin/credentials.json and a project-local .byte/index.json. The CLI creates a .byte/.gitignore so the staging file is not accidentally committed. The short access token is refreshed using the longer-lived CLI token. The CLI token expires after seven days without use and its expiry slides forward when refreshed.
Local link vs published package
npm link to run this checkout; they do not assume the package is published to npm.10 · Persistence map
Where ByteBin data lives
| Store | Main data | Used by |
|---|---|---|
| PostgreSQL | Accounts, tokens, Library metadata, GitHub installations, connections, notifications, conversations, code and commit embeddings. | Next.js app, AI service, history worker |
| MongoDB | Library repository documents and file content. | File service and code indexing |
| Kafka | Temporary event stream for explicit conversation save/delete operations. | Next.js producer and chat-history worker |
| Upstash Redis | Optional, best-effort caches for user, project, and library reads. | Next.js app when configured |
PostgreSQL is the system of record for account and project identity. MongoDB is still part of the current implementation for Library file documents. The search vectors are stored as JSONB and cosine similarity is calculated in the AI service; this codebase does not require a separate vector database.
11 · System map
ByteBin architecture
Follow the main requests from the web app and CLI through the API gateway, private services, model providers, and data stores. The dashed Kafka path is conditional: it is used only when a user saves or deletes conversation history.
Open the interactive diagram in a new tabThe diagram includes source references pinned to the repository revision used when it was generated. It describes the application architecture, not a guarantee of a particular hosting provider’s deployment topology.
12 · Runtime map
Services and APIs
Next.js client
Port 3000 by default. UI, sign-in, protected API routes, Tlux, GitHub App integration, PostgreSQL access, and email requests.
API gateway
Express on 8008. Routes push/update, repository RAG, commit search, and internal Library file operations.
AI & code service
Express on 8009. Applies code push/update operations, indexes repositories, answers code questions, and ranks commits.
File service
Express on 8011. Internal repository file create/read/update/delete operations backed by MongoDB.
Email service
Express on 8012. Validates an internal API key and sends best-effort welcome messages through Resend.
History worker
Kafka consumer. Validates saved-history events, writes them to PostgreSQL, retries transient DB errors, and prunes expired rows.
Service ports are defaults for local development; each process can be configured with environment variables. The gateway and internal service URLs should be private in a production environment.
13 · Trust boundaries
Authentication, access, and safety
- Protected Next.js API routes validate the caller’s access token and resolve the user before reading or changing account data.
- GitHub requests use an installation token and check that the selected repository belongs to an installation for that user.
- The gateway’s repository routes and internal email/file endpoints use shared service keys; keep those values server-side and private.
- CLI credentials are written with restrictive permissions. The CLI filters common secrets and generated files, but you should still review staged files before pushing.
- Tlux asks for confirmation before sending a connection request or deleting a Library project. Git Control keeps applying an AI edit and pushing it as distinct user actions.
- Deleting an account cascades through its owned relational data; external provider credentials and Mongo documents also have cleanup code paths.
Keep secrets out of the browser
14 · Developer setup
Run ByteBin locally
ByteBin is a monorepo with separate Node/Next packages. Install dependencies in the root and each service package, then create local environment files from the matching examples. You will need PostgreSQL, MongoDB, configured AI provider credentials for AI features, GitHub App settings for Git Control, and Docker for local Kafka and the observability profile.
# from the repository root
npm install
npm install --prefix client
npm install --prefix api-gateway
npm install --prefix llms-service
npm install --prefix file-service
npm install --prefix chat-worker
npm install --prefix email-service
# copy the relevant .env.example files to local .env files,
# fill in local credentials, then start the services
npm run devThe root npm run dev starts Kafka, starts the monitoring profile, and launches the client, gateway, AI service, file service, history worker, and email service together. It does not provision PostgreSQL, MongoDB, GitHub App credentials, or model-provider keys for you. Check each package’s .env.example for the variables it reads.
For a smaller loop, run npm run dev --prefix client for the web app and start only the required backend services. The root npm run start starts backend services; start the production Next.js client separately with npm run start --prefix client.
To run the CLI against local ByteBin, link it using the commands in the CLI section and keep its default auth URL at http://localhost:3000 and gateway at http://localhost:8008, or configure the corresponding CLI options/environment values.
15 · Operations
Logs, metrics, and monitoring
ByteBin’s optional local monitoring stack uses Prometheus to scrape service metrics, Loki to store logs, Alloy to collect and forward log files, and Grafana to display dashboards. Kafka Exporter exposes Kafka broker and consumer-topic metrics. The compose profile binds its dashboards and service ports to localhost by default.
npm run monitoring # start Grafana, Prometheus, Loki, Alloy, Kafka Exporter
npm run monitoring:down # stop the observability containers
npm run kafka # start local Kafka only
npm run kafka:down # stop the compose stackOpen Grafana at http://localhost:3001 and Prometheus at http://localhost:9090. Configure credentials in the root environment rather than relying on the local development defaults. Logs need to be written where the Alloy configuration can read them; metrics endpoints are instrumented by the web app and services.
16 · Hosting
Deploying ByteBin
The repository includes a Render Blueprint and a setup note for connecting hosted PostgreSQL, MongoDB, and Kafka. The web app and API gateway are public entry points; file, AI, email, and worker services should communicate over private service addresses wherever the host supports it.
Deployment still requires you to create provider accounts and enter private credentials. Set database URLs, model keys, GitHub App values, service API keys, Kafka TLS/SASL details, email-provider credentials, public app URL, and CORS/trusted-proxy settings in the hosting dashboard.
Review the step-by-step checklist before deploying:
Read the Render deployment guideBackups and expiration
17 · Find your way around
Codebase map and common questions
client/src/appNext.js routes, API handlers, and dashboard pages.
client/src/featuresProduct features: auth, assistant, dashboard, Git, commits, landing, and docs.
client/src/serverAuthentication, PostgreSQL repositories, GitHub integration, Kafka producer, and service clients.
api-gateway/srcExpress route registration, controllers, middleware, and service proxies.
llms-service/srcAI-powered code push/update, RAG, commit retrieval, and model adapters.
file-service/srcMongoDB connection, repository model, and Library file operations.
chat-worker/srcKafka history consumer and PostgreSQL persistence.
byte/binThe `byte` CLI entry point and staging, auth, push, and update commands.
monitoring/Prometheus, Loki, Alloy, Grafana, metrics, and alert rules.
docs/Deployment notes and architecture documentation.
Does ByteBin use PostgreSQL or MongoDB?
Both in the current codebase. PostgreSQL owns accounts, access relationships, project metadata, conversation history, and code/commit embeddings. MongoDB stores Library repository documents and code files.
Does ByteBin save every AI conversation automatically?
No. The explicit Save history action publishes a history event. With saving off, the save endpoint does not send an event to Kafka or write that conversation to the history tables.
Does `byte push` push to GitHub?
No. It uploads staged code into a ByteBin Library project. GitHub edits and pushes happen in Git Control through the GitHub App integration.
Where do I find service API documentation?
The Express services mount Swagger UI at `/api-docs` on their local service ports. The Next.js app also exposes application API routes under `/api`.