Chalkline

Chalkline is a collaborative workspace for practicing software architecture. It combines an infinite whiteboard with typed components, so a database, cache, or queue is more than a labeled shape. Teams can build a system diagram together, share it through a link, and eventually receive feedback based on the architecture they created.

Documentation

• Onboarding: Start here. The whole system in five minutes and a reading path for each subteam.
• Product and team goals: The problem, intended experience, principles, and what the team wants to achieve.
• Architecture: The canvas, semantic graph, synchronization, and persistence plan.
• Roadmap: Product directions and questions for scoping the two terms.
• Team workflow: Subteam ownership, branches, pull requests, reviews, and quality expectations.
• Coding agent guidance: Implementation expectations and agent boundaries.

Most decisions are open to debate and change. We want everyone to get the most from the experience and enjoy building the project together.

Run it locally

You need Bun 1.3.4, Go 1.25, and Docker (only for the database). From the repository root:

make install
make dev

make dev starts the frontend on Vite's default port and the Go server on port 8080. Open the frontend URL to see the canvas; curl localhost:8080/healthz should return {"status":"ok"}. In development, Vite proxies /api and /ws to the server, so frontend code can use same-origin URLs.

Database

Copy .env.example to .env, then:

• make db-up starts the local Postgres container.
• make db-migrate applies the migrations in server/migrations/ to DATABASE_URL using goose. Running it again is safe; applied migrations are skipped.
• make db-down stops the container. Data persists in a Docker volume.

The server does not connect to the database yet. The store's integration tests run against DATABASE_URL after make db-up && make db-migrate, and are skipped when it isn't set.

Checks

Run make check before opening a pull request. It runs the same code checks as CI:

• Frontend: ESLint (type-checked strict rules), tsc (strict), Prettier, Vitest, and a production build.
• Server: gofmt, go vet, go build, and go test -race.

make fmt formats both. You can also run individual frontend scripts from frontend/, such as bun run lint or bun run test.

We plan to work from feature/<short-name> branches into dev at key integration points. Owen and Alan will merge releases from dev into main. See the team workflow for details.