107 lines
4.1 KiB
Markdown
107 lines
4.1 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
|
|
|
|
### Running Services (REPL-driven)
|
|
|
|
```bash
|
|
# Single REPL with all modules
|
|
clj -A:dev:api:web-sm:tui-sm:auth-gw
|
|
|
|
# Individual service REPLs
|
|
clj -M:dev:api # API service
|
|
clj -M:dev:web-sm # Web session manager
|
|
clj -M:dev:tui-sm # TUI session manager
|
|
clj -M:dev:auth-gw # Auth gateway
|
|
```
|
|
|
|
Services expose `(start!)` / `(stop!)` / `(reset!)` in their REPL namespaces.
|
|
|
|
### Testing (Kaocha)
|
|
|
|
```bash
|
|
clj -M:test/unit # Unit tests — no Docker needed
|
|
clj -M:test/integration # Integration — requires Docker (Postgres + MinIO + NATS)
|
|
clj -M:test/e2e # E2E — requires full stack in Docker
|
|
clj -M:test/all # All tiers
|
|
```
|
|
|
|
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/
|
|
```
|