Docs / product/product-knowledge.md

Chimti Product Knowledge

This is a living information file for Chimti. Add raw product rules, client setup notes, demo points, training points, and operating decisions here first. Later this can be reorganized into proper team documentation, client demo material, and training SOPs.

Knowledge Maintenance Rule

Whenever an important Chimti product decision, business rule, architecture change, workflow decision, client/model detail, pricing/services logic, user-role rule, or long-term structure decision is made in chat, add the durable rule to this file along with any code or UI changes. This file is the continuity source for future chats and team documentation, so do not leave important decisions only in implementation code or conversation history.

Documentation Repository Rule

`otlugroup/chimti-docs` is the central repository for long-lived Chimti documentation, including product knowledge, handoffs, architecture notes, app runbooks, deployment notes, workflows, pricing/services rules, and roles/permissions rules. During the transition, this admin-app product knowledge file should remain updated as the working continuity file, and the same durable knowledge should be copied or migrated into `chimti-docs` so documentation does not stay scattered across app repos.

Local Workspace Structure

Local repos under `/Users/jagjeetsinghsethi/Downloads/Code` are organized by product/client group. Chimti repos live under `/Users/jagjeetsinghsethi/Downloads/Code/Chimti`, Otlu repos under `/Users/jagjeetsinghsethi/Downloads/Code/Otlu`, Linklu repos under `/Users/jagjeetsinghsethi/Downloads/Code/Linklu`, and Kelme repos under `/Users/jagjeetsinghsethi/Downloads/Code/Kelme`. Future local path references and handoff docs should use this grouped structure instead of assuming all repos sit directly under `Code`.

Product UI Rules

List Pagination

All main list/register pages in both the user app and admin app should show 10 rows per page by default. This applies to pages such as All Orders, All Customers, Team, Users, Brands, Clients, Modules, Subscriptions, Payments, Shipments, Inventory, Processing Queue, Ads, and other table-based registers. After 10 rows, the page should use Previous / Next pagination with a clear "Showing X-Y of Z" count.

User Creation Team Rule

No user can be created without assigning a team. Every user creation and onboarding flow must require Team, and the save/API layer must reject missing team values instead of silently assigning a fallback.

User App Location Details

The User App must support a dedicated location detail route at `/locations/:locationId`. The Locations list opens this page for the selected store/location. The page should give operators one place to review Overview, Services, Team, Orders & Activity, Shipments, and Settings for that location. Until location-wise service overrides are enabled, the Services and Settings sections should clearly show that pricing, billing modes, turnaround time, processing location, and catalogue rules are inherited from the brand/workspace service setup.

Client Operating Models

Chimti should be able to manage the following client operating models.

Store Only

The client runs one or more stores where most work is managed at the store level. Customer intake, tagging, billing, order handling, and handover can happen from the store. This model fits small operators or brands where each store is operationally independent.

Single Workshop

The client has one main workshop or operations hub. All brands, orders, processing, packing, pickup coordination, and delivery coordination are managed from that single location. This is the current Otlu model.

Store + Workshop

The client has customer-facing stores plus a central workshop. Stores handle intake, tagging, customer communication, and handover. The workshop handles processing, cleaning, packing, and operational production flow.

Hub and Spoke

The client has a main hub/workshop and multiple collection points, counters, stores, or pickup points connected to it. Spokes collect orders and move them to the hub for processing. This model is useful when the brand wants wider area coverage but centralized production control.

Franchise Network

The client or parent group manages multiple franchise locations under one or more brands. Each franchise can have its own store, staff, customers, and local operations, while the parent team can still monitor brand-level performance, permissions, billing, and reporting.

Service Based

Different services can follow different processing paths. For example, laundry may go to a workshop, steam iron may happen at store level, sofa or carpet cleaning may happen at the customer site, and premium dry cleaning can follow a separate workflow. This model is useful when routing depends on service type rather than only store or workshop structure.

Demo Clients by Operating Model

These demo clients are created in the database for demos, training, and internal testing. They are demo-phase records and should not be treated as real customers.

| Operating Model | Demo Client | Demo Brand | What This Demo Shows |

| --- | --- | --- | --- |

| Store Only | NeatNest Care Group | NeatNest Laundry | Two store-led locations where stores manage intake, tagging, billing, handover, and local operations. |

| Single Workshop | AquaFold Works | AquaFold Laundry | One shared workshop/operations hub where all work is managed from a single location. |

| Store + Workshop | WhiteWave Care Group | WhiteWave Laundry | Two customer-facing stores connected to one central workshop for processing and packing. |

| Hub and Spoke | SpinRoute Services | SpinRoute Cleaners | One central hub with multiple collection points/spokes routing work into the hub. |

| Franchise Network | Freshora Care Network | Freshora Laundry | Multiple franchise stores under one parent/brand setup with central visibility and reporting. |

| Service Based | FabricMint Services | FabricMint Care | Different service types route differently: store, workshop, and customer-site service base. |

Demo User App Superadmins

Each demo client has one user app superadmin account. These accounts are for demos, training, and internal testing only.

| Demo Client | Demo Brand | User App Email | Password | Role / Scope |

| --- | --- | --- | --- | --- |

| NeatNest Care Group | NeatNest Laundry | superadmin@neatnest.demo | ViNXa@uALb4433cT@G | Brand Superadmin / Brand scope |

| AquaFold Works | AquaFold Laundry | superadmin@aquafold.demo | pkrZ6QfBCH2AmMr#t# | Brand Superadmin / Brand scope |

| WhiteWave Care Group | WhiteWave Laundry | superadmin@whitewave.demo | h6hGQ35XUiw8BeyN!X | Brand Superadmin / Brand scope |

| SpinRoute Services | SpinRoute Cleaners | superadmin@spinroute.demo | bNLQbRP5B%XWPiRzjh | Brand Superadmin / Brand scope |

| Freshora Care Network | Freshora Laundry | superadmin@freshora.demo | wC@E8bGCkDGA7Xg?VG | Brand Superadmin / Brand scope |

| FabricMint Services | FabricMint Care | superadmin@fabricmint.demo | cacWzLtc7bG7To@i%5 | Brand Superadmin / Brand scope |

Client-Side User Role Options

When creating users for a client/brand workspace, use these role options. The old "Owner" wording should be shown as "Superadmin" in the product UI.

| Role Label | Scope | Typical Use |

| --- | --- | --- |

| Brand Superadmin | Client / Brand | Full workspace control for the business owner or top decision maker. |

| Brand Admin | Brand | Day-to-day setup, stores, services, users, reports, and operations control. |

| Store Manager | Store / Location | Store-level team, customer intake, billing, exceptions, and handover. |

| Store Staff | Store / Location | Counter work, walk-in orders, tagging, payments, and receipts. |

| Operations Manager | Workshop / Hub | Processing queues, QC, production stages, staff, and operational exceptions. |

| Operations Staff | Workshop / Hub | Assigned washing, dry cleaning, ironing, packing, QC, and processing tasks. |

| Customer Care | Brand / Queue | Calls, WhatsApp, pickup booking, customer lookup, complaints, and follow-ups. |

| Accounts User | Brand / Finance | Invoices, dues, payment tracking, settlements, refunds, and finance reports. |

| Field Manager | Field Team | Pickup/delivery assignment, route follow-up, rider exceptions, and field status. |

| Field Executive | Mobile App | Pickup, delivery, customer-site handover, item photos, and task completion. |

Creating the 11th User Type

New user types should be created from the admin app, not by hardcoding a new dropdown value.

Flow:

1. Open Admin App -> Permissions.

2. Switch to Client Role Templates.

3. Click Add User Type.

4. Enter user type name, scope, team, app access, and optional description.

5. Optionally copy permissions from an existing role.

6. Create the role, then open its permission detail page and fine-tune permissions.

7. After save, the role should automatically appear in user creation role dropdowns.

Role metadata:

| Metadata | Purpose |

| --- | --- |

| Scope | Defines whether the role belongs to brand, store/location, workshop/hub, field, finance, or customer experience context. |

| Team | Used for operating team grouping and reporting. |

| App Access | Defines whether the role is mainly for user app, mobile app, or both. |

| Permissions | Controls what modules/actions this user type can access. |

Architecture Decisions - 28 May 2026

These decisions summarize the current intended long-term Chimti structure.

Client, Brand, Location Hierarchy

Chimti should treat Client as the parent group/company and Brand as the operating/billing workspace.

Rules:

1. One client can have one brand or multiple brands.

2. Plans, billing, feature access, module access, service catalog, pricing rules, and TAT rules are brand-level.

3. Users are created in brand/workspace context because future billing can depend on users.

4. A user can later be granted access to multiple brands under the same client without needing a separate login for every brand.

5. Locations are brand-level by default, not client-level.

6. Locations can be Store, Workshop/Hub, Processing Unit, Collection Centre, Service Site, or another configured type.

7. If multiple brands under one client share a hub/factory/workshop, that sharing must be explicitly configured for that client/brand setup. It should not happen automatically.

Billing Level

Billing should be brand-level.

Reason:

Brand Services Scope

Each brand should define whether services/pricing/TAT are:

1. Universal / Brand-level: all locations follow the same setup.

2. Location-wise: each location can override or maintain its own services/pricing/TAT setup.

Switching this setting should show a warning because it can affect existing pricing and operations.

Service Setup Structure

Services setup should not duplicate "select services" above and "configure details" below. The enabled toggle and configuration should be part of the same section.

Service setup flow:

1. Show main services as expandable rows/cards.

2. Each main service has a proper On/Off toggle.

3. When a main service is on, show its internal service items/types.

4. Every internal service item/type can have its own billing mode, TAT, pricing rule, urgent rule, and processing location.

5. Do not rely on one default TAT when item-level TAT is needed.

6. Show only the next relevant fields after previous choices are made.

Pricing rules:

Laundry example:

Module Launch Structure

Admin App -> Modules controls global launch status for User App modules.

Rules:

1. "Module Launch" should be called "Modules".

2. Launch status and global visibility are treated as one practical concept.

3. Launched modules are available for brand-level setup.

4. Planned modules are hidden globally and should not appear in brand module enable screens.

5. Brand-level module settings can enable/disable only launched modules for that brand.

6. User role permissions then decide which user can see/use enabled modules.

7. Module list should be alphabetical and use the same list pattern as All Orders / All Customers.

8. Module detail page controls display tag/badge such as New, Beta, Planned, etc.

Current planned/hidden modules:

Codex-Backed AI Layer

Chimti's AI layer should be available inside the client-facing User App, not only the internal Admin App. The first provider should be Codex CLI installed on the Chimti server, with every AI-enabled Chimti user connecting their own Codex account/profile.

Durable rules:

1. The AI layer must use a backend provider abstraction. Codex CLI is the first provider, but future providers such as OpenAI API, Gemini, Anthropic, or another provider should be pluggable without rebuilding the User App UI.

2. Each Chimti user must have an isolated server-side AI profile for Codex-backed access. One user's Codex account, auth files, usage limits, and outputs must not be shared with another user.

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

4. Codex CLI must run only on the server side. The frontend must never receive Codex auth files, tokens, profile paths, or raw credentials.

5. The User App AI experience can later support chat, AI CEO summaries, workflow help, customer/order lookup, reply drafting, follow-up tasks, reports, and other controlled actions.

6. AI must receive compact, permission-scoped Chimti business context rather than raw database dumps. Context can include current user, role, brand, location, page/module context, recent orders, customers, payments, WhatsApp/call summaries, and relevant links only when the user has access.

7. AI must not get direct database write permission. AI can propose an intent/action; the backend must validate permissions, required fields, business rules, and safety before executing controlled functions.

8. AI access should be controlled by module/plan/role permissions. Brand Superadmin and Brand Admin can be default eligible users when enabled; other roles need explicit AI permission.

9. Codex-backed AI usage should integrate with the prepaid credits/usage ledger where Chimti bears cost or provides paid automation. Even bring-your-own Codex account usage should be logged for audit, limits, support, and abuse protection.

10. Deployment must provide persistent storage for per-user AI profiles and generated AI artifacts if the backend is containerized.

11. Detailed concept note lives in `chimti-docs/architecture/codex-ai-layer.md`.

12. First implementation stores AI setup in `AiSetting`, saved conversations in `AiChat`, and saved messages in `AiMessage`.

13. First API surface uses `/v1/ai/account/status`, `/v1/ai/account/login`, `/v1/ai/models`, `/v1/ai/account/model`, and `/v1/ai/chats/*`.

14. Codex device login is backend-owned: the User App only receives the login URL/code, while the backend runs Codex with a per-user `CODEX_HOME`.

15. Initial Codex message execution uses `codex exec` with read-only sandbox, no approval prompts, an isolated working directory, timeout control, and no direct Chimti database write/action access.

16. Chimti Genie (`/ai-chatbot`) is now treated as a live/default-visible User App module, not a planned hidden module.

Activity and Audit

Activity and Audit are different.

Activity:

Audit:

Shipment Model

Shipment is used whenever articles move from one location to another.

Required flow:

1. Create shipment.

2. Scan articles to add them.

3. Send shipment from source location.

4. Receive shipment at destination location.

5. Reconcile expected vs received articles.

Desktop scanning can use USB scanner keyboard input. Mobile scanning should use camera.

Order Lifecycle Model

Order activity should be nested by domain:

Order confirmation rule:

1. Order Received is created automatically when order is created manually or through automation.

2. Order Confirmed must be a manual action.

3. Team should not proceed to next operational steps until order is confirmed.

Pickup flow:

1. Pickup Scheduled.

2. Pickup Assigned.

3. Pickup Accepted / Rejected / Cancelled by field executive.

4. Reached Pickup Location.

5. Items Received From Customer.

6. Pickup Completed.

7. Handover.

Delivery flow:

1. Delivery Scheduled.

2. Delivery Assigned.

3. Delivery Accepted.

4. Out for Delivery.

5. Reached Customer Location.

6. Handovered to Customer.

7. Delivered.

Customer Communication and Credits

V1 customer communication is for outbound order updates over WhatsApp and SMS.

User app module status:

1. WhatsApp Inbox is enabled as a live user-app module.

2. WhatsApp AI remains separate from the normal WhatsApp Inbox module and should not be treated as automatically enabled by this rule.

3. WhatsApp Inbox should let clients manage customer WhatsApp conversations inside Chimti after connecting their own WhatsApp Business API/provider.

4. Client-owned WhatsApp API setup should support inbound replies, outbound replies, and order/customer context, not only automated order-status messages.

5. WhatsApp Inbox V1 should include Inbox, API Setup, Templates, and Logs sections.

6. Inbox should support conversation status, assignment, quick replies, customer/order context, order-status reply, payment-link reply, and complaint escalation.

7. API Setup should support client-owned providers and Chimti API mode from the same module, while respecting the provider ownership and prepaid-credit rules below.

8. Templates should manage WhatsApp order-event messages and allow event-level enable/disable.

9. Logs should show attempted, sent, held, skipped, and failed WhatsApp outbox messages.

10. Admin app must expose the cross-client Communications/WhatsApp API view inside the Clients section, not as a separate primary sidebar module. It should show, brand-wise and store-wise, whether each scope uses client-owned API, Chimti API, or no provider.

11. Admin Communications view should show wallet balance, used credits, held messages, provider enabled/status, and whether a store setting is direct or inherited from brand/global settings.

12. Actual admin setup for WhatsApp/API ownership must live inside `Clients -> Brand Details -> Communications`, not only in the cross-client report.

13. The Brand Details Communications setup must follow the same mental model as service pricing: select Brand Default for universal setup, or Location Override for a store-specific setup.

14. Store/location WhatsApp settings are configured from the brand context by selecting the store; if no store override is saved, the store inherits the brand default.

15. The Brand Details Communications section should include provider mode, provider credentials, enabled status, connection test, Chimti credits, order-event rules, and recent outbox logs for the selected brand/store scope.

Provider ownership:

1. A brand or store can use its own client-owned provider credentials.

2. A brand or store can explicitly select Chimti API as the primary provider.

3. If a client-owned provider fails, the system must not automatically fallback to Chimti API.

4. Store-level communication settings are a full override of brand settings for that channel or event; if no store setting exists, brand settings apply.

Prepaid credits:

1. Chimti API messages are prepaid-credit based.

2. Credits live in a brand-level communication wallet.

3. Store usage debits the parent brand wallet.

4. WhatsApp and SMS currently cost 1 credit per outbound message unless pricing is changed later.

5. If Chimti API is selected and the brand wallet has insufficient credits, the message must be held/logged instead of sent.

6. Client-owned provider messages do not debit Chimti prepaid credits.

Compliance and audit:

1. Customer `communicationOptIn` must be respected before sending WhatsApp or SMS updates.

2. Every attempted, skipped, held, or sent customer message should be visible in communication outbox history.

Call and AI voice agent direction:

1. Chimti should support brand/store-assigned virtual phone numbers for inbound calls, missed calls, call logs, and callback from the app.

2. Call numbers follow the same brand/store scope model as services and WhatsApp: brand default number first, optional store/location override.

3. The calls module must be AI voice agent-ready, not only human callback. AI agents should be able to answer qualifying calls, fetch customer/order context from Chimti, create follow-up tasks, and hand off to a human user when needed.

4. For India-first telephony, prefer a compliant local telephony provider with virtual numbers, click-to-call, recording, status webhooks, and bidirectional real-time voice streaming to a bot service.

5. The AI voice agent layer should remain provider-pluggable: telephony provider owns numbers/call routing, while Chimti owns customer/order context, permissions, logs, credits/billing rules, and AI tools.

Branding

1. Chimti admin app and user app primary logo surfaces, including login headers and sidebar headers, should use the standalone Chimti wordmark only.

2. OTLU should be presented as a subtle maker/parent-company attribution, not as an inline co-logo with Chimti. Use `A product by` plus the high-quality supplied OTLU SVG from `Downloads/Otlu text/Red Dot + Black “O” on a White Background 2.svg` in the login panel footer/maker line.

3. App-level Chimti branding should not use the icon-only Chimti mark, inline `BY OTLU` lockup, or logo animation unless this decision is explicitly changed later.

Website Launch Page

Before full product launch, Chimti website may use a temporary launching-soon page.

Launch-page rules:

1. Temporary launch page should use the existing website visual language, especially the light gray page background, rounded Chimti-logo blue gradient hero panel using `#18b9fe`, `#14aaf4`, `#0a81d9`, and `#0058be`, oversized white hero text, black/white CTAs, and rounded white content sections.

2. Primary CTA is `Book Early Demo`.

3. Secondary CTA is `Join Early Access`.

4. Founding brand slots should be positioned as priority onboarding, launch pricing discussion, and migration/workflow mapping support, not as a paid preorder unless pricing/payment/legal rules are finalized.

5. Launch-page lead capture should ask for name, business name, city, store count, phone/WhatsApp, email, and first workflow priority.

6. Launch-page positioning should present Chimti as an AI-based laundry operating system: a single dashboard and "AI CEO" for orders, stores, customers, WhatsApp, calls, delivery, payments, reporting, and daily decisions.

7. When using the temporary Mistral-style website shell for Chimti, the global header must use Chimti's own text logo instead of the reference site's mark.

8. Chimti's temporary website header should use the normal full Chimti wordmark only. Do not show the `BY` label, OTLU text logo, icon-only Chimti mark, or logo animation unless this decision is explicitly changed later.

9. The temporary Mistral-style home page should use Chimti logo colors for important brand moments and accents, especially `#18b9fe`, `#14aaf4`, `#0a81d9`, and `#0058be`; avoid leaving primary accents in the reference site's orange/red palette.

10. The active temporary website folder is connected to the `otlugroup/chimti-website` GitHub repository on the `v2` branch. The archived original website remains separate and should not be overwritten unless explicitly requested.

11. Chimti website favicon should use the colored Chimti icon SVG, served from `/favicon.svg`, and should be linked across all mirrored website pages.

12. Chimti website home-page copy should stay within the existing Mistral-style sections while replacing reference-site messaging with Chimti-specific positioning: an AI-based laundry operating system and "AI CEO" for orders, stores, customers, WhatsApp, calls, delivery, payments, reporting, client/store setup, credits, printing, and launch support.

13. The pre-launch website page lives at `/pre-launch/` in the website repo. It should use launch-specific copy with `Launching Soon` as the launch timing message and must not show a launch date unless explicitly decided later.

14. For now, Chimti website's blue hero animation should remain the original animation from the temporary website shell. Do not replace it with custom laundry icon or command-center/dashboard visuals unless a new direction is explicitly approved.

15. Chimti website top header menu should use five primary items in this order: `Features`, `Solutions`, `Pricing`, `Developers`, and `Company`. Keep `Pricing` as a top-level direct link. Avoid separate top-level `Updates`, `Clients`, `Modules`, or `API & agents` labels unless this navigation structure is explicitly changed later.

16. Public website feature messaging should focus on the client-facing User App and Mobile App, not Chimti's internal Admin App. Admin App capabilities are for Chimti/Otlu team control and should not be positioned as customer product features unless a specific internal/admin-facing page is being written.

17. Chimti website `Features` dropdown should list these 10 client-facing User App feature groups: AI CEO Dashboard, Orders & Billing, Customer CRM, Pickup & Delivery Management, Store & Workshop Operations, Article Tags & Scanning, WhatsApp & Customer Communication, Calls & Follow-ups, Shipments & Location Transfers, and Reports, Team & Permissions.

18. Chimti website `Features` dropdown items should keep the original website shell's icon-led navigation style: each item gets a sharp 40px solid-color square icon tile with a white feature mark, the hover-in arrow on the left, and the trailing pixel arrow on the right.

19. Each of the 10 `Features` dropdown items should have a dedicated website page under `/features/`: `/features/ai-ceo-dashboard/`, `/features/orders-billing/`, `/features/customer-crm/`, `/features/pickup-delivery-management/`, `/features/store-workshop-operations/`, `/features/article-tags-scanning/`, `/features/whatsapp-customer-communication/`, `/features/calls-follow-ups/`, `/features/shipments-location-transfers/`, and `/features/reports-team-permissions/`. The dropdown links should point directly to these pages.

20. Chimti website feature detail pages must include an explicit fixed-header top offset so the eyebrow/breadcrumb and hero content never sit behind the fixed global header.

21. Chimti website About page should position Chimti as an AI operating system for laundry businesses. It should focus on laundry operations, store/counter/workshop/customer workflows, and OTLU ownership, and must avoid unverified founder, customer-logo, or broad AI-lab claims.

Deployment

1. Chimti development deployments live in Coolify under the `Otlu` project, `development` environment, on the Otlu server.

2. Every Chimti repo should have a deployable service record in that Coolify development environment so repo status can be verified from one place.

3. Current development service domains should use the `chimti-*.otlu.io` pattern:

- API: `https://chimti-api.otlu.io`

- User app: `https://chimti-user-app.otlu.io`

- Admin app: `https://chimti-admin-app.otlu.io`

- Website: `https://chimti-website.otlu.io`

- Customer app: `https://chimti-customer-app.otlu.io`

- User mobile web: `https://chimti-user-mobile-app.otlu.io`

- Docs: `https://chimti-docs.otlu.io`

- Print agent dev service: `https://chimti-print-agent.otlu.io`

4. The website deployment should track the `v2` branch of `otlugroup/chimti-website` unless the active website branch decision changes.

5. The deployed print-agent service is only a development/reference service. Real printing still requires the local print agent installed on the store desktop connected to the USB printer.

6. Admin and user web apps must set their app variant explicitly at build/deploy time. The admin app must build with `VITE_APP_VARIANT=admin`; if this is missing, it can render user/workspace login copy and user-facing access rules on the admin domain. The admin app repo should default to admin mode as a fallback.

Printing and Tags

Chimti uses article tags for garment tracking.

Current tag printer assumptions:

Browser limitation:

Tag content:

User App UI Rules

1. Sidebar modules should load only after module configuration is known, so hidden/planned modules do not flash before disappearing.

2. Admin app should not have menu customization.

3. User app menu customization should save only when the user clicks Save.

4. All list/register pages should show 10 rows per page.

5. Popups should be centered, content-sized, Esc-closeable, and should warn once if unsaved data exists.

6. Audit should not show in user app.

7. Notes are append-only and cannot be edited/deleted.

8. Breadcrumbs should appear on detail pages.

9. Details pages should use tabs that switch content, not scroll anchors.

10. Details pages should avoid list counters at the top.

New Chat Handoff

A fuller continuation summary was saved at:

`/Users/jagjeetsinghsethi/Downloads/Code/Chimti/chimti-docs/handoffs/2026-05-28-new-chat-handoff.md`