149 lines
5.7 KiB
Markdown
149 lines
5.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
ajet-chat is a Clojure monorepo for a team messaging platform (Slack-like). Early stage — module skeletons exist but most code is stubbed out.
|
|
|
|
## Repository Structure
|
|
|
|
Monorepo with `:local/root` deps linking modules:
|
|
|
|
- **shared/** — Common DB layer (next.jdbc + HoneySQL), EventBus (NATS via jnats), API client SDK, schemas, protocols
|
|
- **auth-gw/** — Auth gateway: http-kit edge proxy, session/token validation, routing (has PG access)
|
|
- **api/** — Stateless REST API: all data reads/writes to PG, publishes events to NATS
|
|
- **web-sm/** — Web session manager: Hiccup + Datastar SSE for browsers (NATS + API, no PG)
|
|
- **tui-sm/** — TUI session manager: SSE for terminal clients (NATS + API, no PG)
|
|
- **cli/** — Terminal client: CLI (one-shot) + TUI (interactive via clojure-tui)
|
|
- **mobile/** — Mobile client (deferred, placeholder only)
|
|
|
|
**Dependency matrix:**
|
|
```
|
|
PG NATS API(HTTP)
|
|
API yes pub —
|
|
Auth GW yes — —
|
|
Web SM — sub yes (internal)
|
|
TUI SM — sub yes (internal)
|
|
CLI — — yes (external, via Auth GW)
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
### Task Runner (Babashka)
|
|
|
|
Preferred way to run tasks — `bb` wraps `clj` commands and manages Docker infra automatically.
|
|
|
|
```bash
|
|
bb tasks # List all available tasks
|
|
|
|
# Development
|
|
bb dev # Start dev infra + nREPL (all modules)
|
|
bb infra:dev # Start dev Docker infra only
|
|
bb infra:dev:stop # Stop dev Docker infra
|
|
|
|
# Testing
|
|
bb test # All tests (starts test infra)
|
|
bb test:unit # Unit tests only (no Docker needed)
|
|
bb test:integration # Integration tests (starts test infra)
|
|
bb test:e2e # E2E tests (starts test infra)
|
|
|
|
# Per-module testing
|
|
bb test:shared # All shared tests
|
|
bb test:shared:unit # Shared unit tests only
|
|
bb test:api # All API tests
|
|
bb test:api:unit # API unit tests only
|
|
bb test:auth-gw # All auth-gw tests
|
|
|
|
# Per-module bb.edn (from module directory)
|
|
cd shared && bb test:unit # Delegates to root bb.edn
|
|
|
|
# Build & Deploy
|
|
bb build api # Build uberjar for a module
|
|
bb clean api # Clean module artifacts (or bb clean for all)
|
|
bb prod # Start production stack (docker compose)
|
|
bb prod:stop # Stop production stack
|
|
bb prod:logs # Tail production logs
|
|
|
|
# Database
|
|
bb db:reset-test # Drop & recreate test DB schema
|
|
```
|
|
|
|
### Running Services (REPL-driven)
|
|
|
|
```bash
|
|
# Via bb (recommended)
|
|
bb dev # nREPL with all modules + dev infra
|
|
|
|
# Via clj directly
|
|
clj -A:dev:api:web-sm:tui-sm:auth-gw # Single REPL with all modules
|
|
clj -M:dev:api # Individual service REPL
|
|
```
|
|
|
|
Services expose `(start!)` / `(stop!)` / `(reset!)` in their REPL namespaces.
|
|
|
|
### Testing (Kaocha)
|
|
|
|
```bash
|
|
# Via bb (recommended — manages Docker infra automatically)
|
|
bb test:unit # Unit tests — no Docker needed
|
|
bb test:integration # Integration — starts Docker automatically
|
|
bb test # All tiers
|
|
|
|
# Via clj directly (legacy — requires manual Docker management)
|
|
clj -M:test/base:test/unit # Unit tests
|
|
clj -M:test/base:test/integration # Integration tests
|
|
clj -M:test -m kaocha.runner # All tests (using unified :test alias)
|
|
```
|
|
|
|
Docker infra for integration tests: `docker compose -f docker-compose.test.yml up -d`
|
|
|
|
### Architecture Diagram
|
|
|
|
```bash
|
|
typst compile architecture.typst architecture.png
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Request flow:** Internet → nginx (TLS, prod only) → Auth Gateway → service (API / Web SM / TUI SM)
|
|
|
|
**Key pattern — data vs events separation:**
|
|
- All persistent data reads/writes go through the **API** (stateless REST, only service with PG access besides Auth GW)
|
|
- Real-time events flow via **NATS** pub/sub (community-scoped subjects)
|
|
- **Session managers** hold live client connections, subscribe to NATS for events, fetch full data from API via HTTP. No direct PG connection.
|
|
- SMs publish ephemeral events (typing indicators) directly to NATS — bypasses API for latency
|
|
|
|
**Auth Gateway** is a Clojure http-kit proxy that does its own DB reads/writes for session validation, then routes authenticated requests to internal services.
|
|
|
|
## Tech Stack
|
|
|
|
- All server modules: Clojure 1.12, http-kit 2.8, reitit 0.7, Ring 1.13
|
|
- Data: PostgreSQL (next.jdbc + HoneySQL) — API + Auth GW only
|
|
- Events: NATS (io.nats/jnats) — API publishes, SMs subscribe
|
|
- Web: Hiccup 2.0 + Datastar SDK (web-sm)
|
|
- CLI: shared API client SDK (babashka http-client) + clojure-tui (local dep at `../../clojure-tui`)
|
|
- Files: MinIO (S3-compatible)
|
|
|
|
## Conventions
|
|
|
|
- **PostgreSQL everywhere** — same DB in dev and prod, no SQLite. Dev infra runs in Docker.
|
|
- **HoneySQL maps** for all queries — avoid raw SQL strings
|
|
- **Migratus** for schema migrations
|
|
- **NATS** for all event pub/sub — community-scoped subjects (`chat.events.{community-id}`), DM subjects (`chat.dm.{channel-id}`)
|
|
- **MinIO** (S3-compatible) for file storage — same API as AWS S3
|
|
- **UUIDs** for all entity IDs (`java.util.UUID/randomUUID`)
|
|
- **EventBus protocol**: `publish!`, `subscribe!`, `unsubscribe!` — backed by NATS
|
|
- **SSE** for all server→client streaming (web + TUI), HTTP POSTs for client→server signals
|
|
|
|
## Namespace Conventions
|
|
|
|
```
|
|
ajet.chat.shared.* — shared/src/
|
|
ajet.chat.api.* — api/src/
|
|
ajet.chat.web.* — web-sm/src/
|
|
ajet.chat.tui-sm.* — tui-sm/src/
|
|
ajet.chat.auth-gw.* — auth-gw/src/
|
|
ajet.chat.cli.* — cli/src/
|
|
```
|