---
title: "Architecture"
description: "Local Hafi components, message flow, state, credentials, and current verification limits."
---

> Documentation Index
> Fetch the complete documentation index at: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

# CLI architecture

Hafi is a local TypeScript and Bun CLI. Its first workflow reads Gmail or Lark messages, asks Jev whether a personal reply is needed, and saves a suggested draft locally.

```text
Codex / Claude Code IDE ──> onboarding and review commands
OS cron or terminal ─────> hafi run-once --workflow hafi.yaml
                              │
                         runOnce() ── SQLite
                              │
                   GmailSource or LarkSource
                              │
                        Jev evaluator
                              │
                   save_reply_draft action
                              │
                         Codex CLI
                              │
                      local draft result
```

## Components

`InboxSource` is implemented by Gmail and Lark adapters. Each adapter returns a common inbox item with a provider reference and bounded conversation context. The runner reads a validated workflow, claims a run lease, fetches new items, evaluates conversations, runs the supported action, and records results. The CLI renders output as text or JSON.

System cron runs a short-lived process. SQLite stores provider cursors, work items, run status, and reviewable drafts. A cursor and its queued message references are saved together. Failed Jev or Codex calls keep work retryable, and repeated runs are designed to avoid duplicate results.

## Baselines and provider coverage

The first run establishes an inbox baseline so old messages do not become new work. Gmail uses history-based sync. Lark uses per-chat baselines for chats the user authorized. Lark's user-identity chat list documents `types=p2p,group` for direct and group chats, and Hafi requests both. Live permissions and message coverage still need end-to-end verification.

## Local data and safety

OAuth tokens and API keys belong in the operating system credential store, outside YAML and the repository. Drafts and workflow state are private local files. The first workflow does not send replies or notifications.

## Status

The CLI and core workflow are implemented. Live provider behavior still requires account verification, and there is no release binary yet. A future web UI could reuse the core; it is not implemented.

Source: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/architecture/index.mdx