Architecture
How ChatJS is structured and how data flows through the system
System Overview
The current ChatJS application uses:
- Next.js App Router for the frontend and API routes
- EVE for conversation execution, message persistence, tool calls, and stream recovery
- PostgreSQL (via Drizzle ORM) for application-owned metadata such as users, ownership, projects, sharing, files, documents, and billing evidence
- AI SDK to connect to multiple AI providers through a gateway abstraction
- Files SDK through a configured file storage provider for attachments and generated media
- tRPC for end-to-end type-safe API routes between client and server
EVE conversation flow
When a user sends a message:
EVE runs conversations and persists their messages and execution state. ChatJS manages authentication, chat organization, sharing, files, documents, and billing.
Core and optional extensions
Core owns account authentication, conversation ownership, EVE execution, model resolution, and usage evidence. Installed plugins add capabilities such as Projects, Sharing, Model Preferences, and Credits. Tools and providers have separate installation contracts.
See Configuration & Extensions for the available extension types and Source Ownership for where to make changes.
Usage evidence
Core records model usage under unique accounting-wrapper attempt IDs and supported tool usage under session/call IDs. It reconciles tool receipts against the authoritative EVE stream. Replaying evidence with the same identity does not duplicate recorded usage. This recording and reconciliation also runs without Credits installed, without creating or debiting balances. Reconciliation failures can prevent new work.
Credits owns balance checks and charging policy. Its page explains how recorded usage becomes a debit when the plugin is installed.