From 2d43b878391fa1755c81c04bed99c42d9f5e7ec8 Mon Sep 17 00:00:00 2001
From: James Magahern <james@magahern.com>
Date: Thu, 12 Jun 2025 20:36:18 -0700
Subject: [PATCH] add CLAUDE.md

---
 CLAUDE.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..99ff308
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+```bash
+# Setup build directory (first time)
+meson setup builddir
+
+# Build project
+meson compile -C builddir
+
+# Clean rebuild
+rm -rf builddir && meson setup builddir && meson compile -C builddir
+
+# Run the application
+./builddir/src/kordophone
+```
+
+## Architecture Overview
+
+Kordophone is a GTK4/Libadwaita messaging client written in Vala that acts as a frontend to a separate DBus daemon (`kordophonecd`). The application follows a clean separation of concerns:
+
+### Core Architecture
+- **DBus Client**: This GTK app connects to `net.buzzert.kordophonecd` daemon over DBus
+- **Split UI**: Main window has conversation list sidebar + transcript view
+- **Custom Rendering**: Transcript uses Gtk.DrawingArea with snapshot API for performance
+- **Repository Pattern**: All data operations go through `Repository` singleton which proxies to DBus service
+
+### Key Components
+- **Application** (`src/application/`): App lifecycle, main window, preferences
+- **Service** (`src/service/`): DBus integration, data repository, settings management  
+- **Conversation List** (`src/conversation-list/`): Sidebar with conversation list and search
+- **Transcript** (`src/transcript/`): Message display with pluggable bubble layouts
+- **Models** (`src/models/`): Data structures (Conversation, Message, Attachment)
+
+### DBus Interface
+The app depends on a running `kordophonecd` daemon that provides:
+- **Repository interface**: Conversation/message CRUD, real-time sync via signals
+- **Settings interface**: Server configuration, user credentials
+
+### Development Notes
+- Vala compiles to C, build artifacts in `builddir/`
+- DBus interfaces auto-generated from XML: run `src/service/interface/generate.sh`
+- Resources bundled via GResource (`src/resources/kordophone.gresource.xml`)
+- Custom CSS styling in `src/resources/style.css`
+- Application ID: `net.buzzert.kordophone2`
+
+### Message Layout System
+Transcript view uses a pluggable layout system in `src/transcript/layouts/`:
+- `BubbleLayout`: Base class for message bubbles
+- `TextBubbleLayout`: Text messages
+- `ImageBubbleLayout`: Image attachments
+- `DateItemLayout`: Date separators
+- `SenderAnnotationLayout`: Sender labels
+
+All layouts render to Cairo context via Gtk snapshot API for efficient scrolling performance.
\ No newline at end of file