Docs / architecture/codex-ai-layer.md

Chimti Codex AI Layer Concept

This document captures the intended AI layer concept for Chimti. It is adapted from an older project concept, but only the pieces relevant to Chimti should be carried forward.

Core Idea

Chimti should provide an AI layer inside the client-facing User App. The first backend provider for this layer will be Codex CLI installed on the server where Chimti is deployed.

Each Chimti user who gets AI access should connect their own Codex account. The backend should run Codex CLI using that user's isolated server-side profile, so one user's Codex login, tokens, limits, and outputs are never shared with another user.

The UI capabilities can evolve later. Initially, the durable architecture decision is:

1. User App exposes AI features to approved client users.

2. Backend owns provider execution and credentials.

3. Codex CLI is the first provider.

4. Provider abstraction must allow future providers such as OpenAI API, Gemini, Anthropic, or another local/server AI provider without rebuilding the User App UI.

Naming

Product-facing names can be decided later, but the architecture can use these working terms:

Provider Abstraction

The backend should not hardcode Codex CLI directly into UI routes. Add an AI provider abstraction with a stable interface such as:


type AiProvider = {

  complete(input: {

    userId: string;

    brandId?: string;

    locationId?: string;

    messages: AiMessage[];

    context: AiContext;

    model?: string;

  }): Promise<AiCompletionResult>;



  getAccountStatus(input: { userId: string }): Promise<AiAccountStatus>;

  startLogin(input: { userId: string }): Promise<AiLoginStartResult>;

  getLoginStatus(input: { userId: string; loginId?: string }): Promise<AiLoginStatus>;

  cancelLogin(input: { userId: string; loginId?: string }): Promise<void>;

  listModels(input: { userId: string }): Promise<AiModel[]>;

  updateModel(input: { userId: string; model: string }): Promise<void>;

};

Initial provider:

Future providers:

Codex CLI Integration

Rules:

1. Codex CLI runs only on the server side.

2. Frontend never receives Codex auth files, profile files, tokens, or raw credentials.

3. Every Chimti user who uses Codex-backed AI gets a separate AI profile.

4. User email must not be used directly as a folder name. Use an internal user id or hashed/safe profile id.

5. Suggested storage:


/data/chimti/ai-profiles/<provider>/<hashed-user-id>/

6. The backend starts Codex CLI with that isolated profile/config path.

7. Account status should show connected/disconnected, provider, current model, and limit or error state when available.

8. Login flow should be frontend-driven but backend-owned:

- Connect Codex

- Switch account

- Logout/disconnect

- Login URL/code shown in UI when the provider returns them

- Polling states: pending, connected, failed, expired

User Scope and Access

AI access should be controlled per client user and role. Not every User App user should automatically get AI access.

Initial access rules:

1. Brand Superadmin and Brand Admin can be eligible for AI by default when the module is enabled.

2. Store, workshop, accounts, customer care, and field roles should require explicit AI permission.

3. AI context must be scoped to the user's authorized client, brand, locations, teams, and modules.

4. A user must never be able to ask AI for data from a brand/location they cannot access in Chimti.

Context Layer

AI should not receive only the raw user prompt. Backend should attach a compact, permission-scoped business context.

Potential context:

Rules:

1. Keep context compact.

2. Do not dump raw database tables into prompts.

3. Only include records the user is allowed to access.

4. Prefer summaries and IDs/links over huge raw payloads.

5. If required context is missing, AI should ask a clarifying question instead of guessing.

Action Layer

The AI layer should eventually do useful work, not only chat. However, AI must not get direct database write access.

Allowed pattern:

1. AI proposes an intent/action.

2. Backend validates permissions, required fields, business rules, and safety.

3. Backend executes a controlled function.

4. Backend writes the result to the database.

5. UI shows the result, link, and any required confirmation.

Potential future AI actions:

Direct arbitrary shell command execution must not be exposed as an AI action.

Data Storage

Suggested backend data structures:

- id

- user_id

- client_id

- brand_id

- location_id nullable

- title

- provider

- model

- created_at

- updated_at

- id

- chat_id

- role: user, assistant, system, tool

- content

- provider

- model

- metadata json

- created_at

- user_id

- default_provider

- default_model

- ai_profile_id

- status

- created_at

- updated_at

- id

- chat_id

- user_id

- action_type

- status

- input json

- result json

- created_at

- completed_at

- id

- user_id

- chat_id

- type

- title

- storage_url or file_path

- mime_type

- metadata json

- created_at

API Shape

Exact route names can change with the current API conventions, but the backend should expose these capability groups:

Credits and Billing

Chimti's AI layer should integrate with the prepaid credits model.

Rules:

1. Codex-backed AI access can be enabled as a plan feature or add-on.

2. Usage that creates provider cost, heavy processing, documents, calls, WhatsApp messages, or other paid automation should be recorded in usage logs.

3. Where billing applies, deductions should come from the client/brand prepaid credits wallet.

4. Even if a user brings their own Codex account, Chimti should still track internal AI usage for audit, limits, support, and abuse protection.

Security Rules

1. Never expose Codex auth files/tokens to frontend.

2. Never share one user's Codex profile with another user.

3. Store AI profiles in isolated server-side directories.

4. Use safe hashed/internal IDs for profile folders.

5. Protect all AI routes with Chimti auth and permission checks.

6. Scope generated documents/artifacts to the user/client/brand.

7. Do not create a general "run shell command" endpoint.

8. Codex CLI calls must have timeout and cancellation behavior.

9. Logs must mask secrets, tokens, login codes, and credential paths.

10. Add rate limits and abuse controls before production use.

Deployment Rules

The deployment must provide persistent storage for:

Suggested environment variables:


CODEX_CLI_BIN=codex

CODEX_DEFAULT_MODEL=gpt-5

CODEX_MODEL_OPTIONS=gpt-5,gpt-5-mini

CODEX_EXEC_TIMEOUT_MS=120000

AI_PROFILE_STORAGE_PATH=/data/chimti/ai-profiles

AI_WORKSPACE_STORAGE_PATH=/data/chimti/ai-workspaces

Docker/VPS deployment must mount the profile/artifact paths as persistent volumes if the backend is containerized.

First Implementation Status

The first Chimti implementation is now scoped to account connection and persisted chat:

1. API schema uses `AiSetting`, `AiChat`, and `AiMessage`.

2. API routes are available under `/v1/ai/account/*`, `/v1/ai/models`, and `/v1/ai/chats/*`.

3. User App `Chimti Genie` uses the new account status, Codex device-login, model selector, saved chat list, and persisted messages.

4. Codex CLI runs server-side with isolated per-user `CODEX_HOME`.

5. Device login returns only the login URL and one-time code to the User App.

6. Message execution uses `codex exec` with read-only sandbox, no approval prompts, isolated workspace, timeout, and no direct database write/action access.

7. Existing Chutes-backed photo pricing and legacy `/v1/ai/chat` route remain in place for compatibility.

8. Chimti Genie (`/ai-chatbot`) is a live/default-visible User App module for this rollout.

Rollout Phases

Phase 1: Architecture and Login

Phase 2: Chat

Phase 3: Chimti Actions

Phase 4: Automation and Billing

Current Open Decisions

These can be decided later:

1. Final product name: AI Assistant, AI CEO, Chimti AI, or another name.

2. Which roles get AI access by default.

3. Whether client users must bring their own Codex account or Chimti can also offer a managed provider option.

4. Which first actions are allowed in the User App.

5. Exact usage/credits pricing.

6. Whether AI chat appears as a global module, page-level assistant, or both.