docsContributing

Contributing

⚠️

A full contribution policy is being prepared. Until it lands, please reach out before opening pull requests so we can discuss scope and direction:

Issues and discussions remain open for bugs, questions, and design conversations — see the links at the bottom of this page.

The repo’s existing developer guide lives at the root:

👉 CONTRIBUTING.md on GitHub

It covers the quick start, the architecture, the verification workflow, the conventions, the PR workflow, and a section dedicated to AI coding agents working in the codebase. Treat it as background reading — the formal policy that supersedes it is still in progress.

The TL;DR for newcomers:

  1. Clone, install, run bin/preflight — type-checks the whole monorepo via turbo. If green, your environment is sound.
  2. Adding a new query the agent can run? It’s three files, ~20 lines total. See the architecture doc.
  3. Run bin/preflight (lint + build) before opening a PR. For testing UI changes, bin/devserve (or smartchats dev) gives you hot reload.

Running from source

The user-facing install (curl | sh from Quick Start) ships compiled binaries. For development you want the source path:

git clone https://github.com/sheunaluko/smartchats.git
cd smartchats
npm install

Two ways to run the stack while iterating:

# Hot-reload Next.js dev server + Express + SurrealDB container
bin/devserve
 
# Or via the CLI (same thing, wrapped):
cd packages/smartchats-cli
npm link    # makes the local `smartchats` binary point at your source
smartchats dev

bin/devserve is the canonical dev loop — hot reload, TypeScript watch mode, no container rebuild on each change. smartchats start is for end users and for production-mode validation. Most contributor time is in dev.

⚠️

Don’t run npm run dev at the root. Turbo’s fan-out used to fire the MCP server’s dev script, which spawns a Firebase OAuth browser flow. That script has been renamed (mcp/package.json:scripts/dev:stdio) but it’s still better to use bin/devserve or smartchats dev — they target only the processes you actually need.

Useful bin/ scripts

ScriptWhat it does
bin/preflightLint + workspace type-check + build. Run before every PR.
bin/devserveHot-reload dev stack (Next.js dev + Express + SurrealDB container)
bin/aioBuild + run the all-in-one Docker container. Production-mode validation.
bin/cloud_test_dbLocal SurrealDB with the cloud schema, for closed-target testing
bin/checkpoint "<msg>"git add -A && git commit -m "checkpoint: <msg>"
bin/save_sessionExport the current session bundle for triage
bin/test-bun-deploySmoke-test the no-Docker, bun + native-surreal production path

Repo layout (high level)

smartchats/
├── apps/
│   └── smartchats/                # Next.js app (chat UI, voice, KG) — static SPA
├── packages/
│   ├── smartchats-backend/        # DataAPI contract (types only)
│   ├── smartchats-backend-firebase/  # Cloud-target backend adapter
│   ├── smartchats-backend-local/     # Local-target backend adapter
│   ├── smartchats-cloud-client/   # Open client for the hosted cloud
│   ├── smartchats-cli/            # `smartchats` command (setup, start, etc.)
│   ├── smartchats-database/       # SurrealDB queries + operations + DataAPI factories
│   ├── smartchats-local-server/   # Express server: serves SPA + /local-api/*
│   ├── smartchats-mcp/            # MCP server
│   └── ...
├── bin/
│   ├── preflight                  # Lint + type-check + build
│   ├── devserve                   # Hot-reload dev stack
│   ├── aio                        # Docker AIO container
│   ├── cloud_test_db              # Local SurrealDB for cloud-shape testing
│   ├── checkpoint                 # `git add -A && git commit -m "checkpoint: …"`
│   ├── test-bun-deploy            # Smoke-test the bun + native-surreal path
│   └── ...
└── CONTRIBUTING.md                # The canonical guide

Architecture invariants

These are load-bearing. Don’t break them without discussion:

  • Single direct importer of surrealdb: only packages/smartchats-database/src/client.ts imports the npm package. Every other consumer goes through the Client interface.
  • One credential store. ~/.smartchats-mcp/credentials.json shared by CLI + MCP. Don’t invent a parallel auth file.
  • The DataAPI contract is the read/write boundary. Don’t add alternative dispatcher abstractions.
  • Per-statement errors must surface. No silent [] on status: ERR.

See Architecture → Open vs closed for the package-level reasoning.

For AI coding agents

SmartChats is built collaboratively by humans and AI coding agents. The same conventions apply to both — same quality bar, same review process, same guide. This section captures what tends to make agent contributions land well:

  • Read existing code before writing new code. Most patterns you’ll reach for already exist somewhere — search first, then write. The layered architecture means nearly every “I need to add X” maps to exactly one place.
  • Make small, surgical changes. A feature should usually touch one builder, one tool wrapper, and one CLI command — not five files. When the diff sprawls, you’re working against the architecture.
  • Run bin/preflight before declaring done. Don’t rely on CI alone for your own change. For UI-affecting work, also bring up the stack with bin/devserve or smartchats dev and verify the change in a browser.
  • For destructive actions (deleting data, force-pushing, modifying live cloud, killing shared processes), confirm with the user first. Reversibility is a one-way valve.
  • When tests fail, find the cause. Don’t blame “flaky environment” or “pre-existing issues.” Read the log, reproduce the case, fix the root cause.
  • Track architecture-improvement ideas in data/ARCHITECTURE_NOTES.md rather than refactoring as you go. The maintainer reviews these before they ship.
  • Match the existing tone. Doc edits should sound like the surrounding text. Code edits should match the surrounding style. Comment density matches the file’s norm.

Re-read this section at the start of each session. It’s the fastest way to load project conventions and avoid the most common agent-contribution failure modes.

Help / Discussion

For larger architectural changes, please email before opening an issue or PR so we can align on scope.

Thanks for your interest in contributing.

MCP Server