mirror of
https://github.com/colanode/colanode.git
synced 2026-02-24 11:59:53 +01:00
6590a0db0f
* add contributing md and coding agents md docs * remove contributing md from this branch * minor updates * resolve PR comments and add tests instructions
48 lines
3.2 KiB
Markdown
48 lines
3.2 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Architecture Overview
|
|
Colanode is a local-first collaboration workspace. Clients keep a local SQLite cache and sync to the server (Fastify + Postgres + Redis) in the background for offline-first behavior. Real-time editing uses CRDTs (Yjs) to merge concurrent changes. Shared packages provide core types, sync logic, and UI; see `README.md` for product and hosting context.
|
|
|
|
## Project Structure & Module Organization
|
|
- `apps/`: client and server apps (`server`, `web`, `desktop`, `mobile`).
|
|
- `packages/`: shared libraries (`core`, `client`, `ui`, `crdt`).
|
|
- `scripts/`: asset and seed tooling (postinstall runs from here).
|
|
- `hosting/`: Docker Compose and Kubernetes (Helm) deploy configs.
|
|
- `assets/`: repository images used in docs.
|
|
|
|
## Development Guide (Quick Start)
|
|
- Install dependencies: `npm install`.
|
|
- Prefer running tasks in individual app/package directories; repo-level scripts run the entire monorepo.
|
|
- Run apps directly:
|
|
- `apps/server`: `cp .env.example .env && npm run dev`
|
|
- `apps/web`: `npm run dev` (Vite on port 4000)
|
|
- `apps/desktop`: `npm run dev`
|
|
- Local dependencies: `docker compose -f hosting/docker/docker-compose.yaml up -d`.
|
|
|
|
## Coding Guidelines
|
|
- Ground changes in the existing codebase. Start from the closest feature and mirror its folders, naming, and flow.
|
|
- Keep shared behavior in `packages/`; keep `apps/` thin and focused on wiring and UI.
|
|
- Server routes use Fastify plugins with Zod schemas from `@colanode/core`. Update schemas and error codes before handlers.
|
|
- Client operations follow the query/mutation pattern: define typed `type: 'feature.action'` inputs/outputs in `packages/client/src/queries` or `packages/client/src/mutations`, then wire handlers in `packages/client/src/handlers`.
|
|
- Use Kysely (`database`) for SQL access and limit raw SQL.
|
|
- UI styling uses Tailwind utilities, shared styles in `packages/ui/src/styles`, and shadcn components in `packages/ui/src/components/ui`. Prefer shared components over one-off styling.
|
|
- Use `@colanode/*` imports and follow ESLint import grouping; keep filenames consistent with nearby code.
|
|
|
|
## Server Configuration
|
|
- Config file location: set via `CONFIG` environment variable (e.g., `CONFIG=/path/to/config.json`).
|
|
- If `CONFIG` is not set, server uses schema defaults from `apps/server/src/lib/config/`.
|
|
- Template: `apps/server/config.example.json`.
|
|
- Reference resolution in JSON:
|
|
- `env://VAR_NAME` - resolves to environment variable (required, fails if not set).
|
|
- `file://path/to/file` - reads and inlines file contents (useful for certificates).
|
|
- Direct values - plain strings/numbers/booleans for non-sensitive settings.
|
|
- Only `postgres.url` is required (defaults to `env://POSTGRES_URL`); all other settings have schema defaults.
|
|
- For production: copy `config.example.json`, update values, mount it, and set `CONFIG` + required env vars.
|
|
- Storage config via `storage.provider.type`: `file` (default), `s3`, `gcs`, or `azure`.
|
|
- See `apps/server/src/lib/config/` for full schemas and validation.
|
|
|
|
## Testing
|
|
- Tests live in `apps/server` and `apps/web` and run with Vitest.
|
|
- Run `npm run test` in the relevant app directory; `npm run test` at the repo root runs them via Turbo.
|
|
- Validate changes manually where tests do not apply and note verification steps.
|