Overview

ARK products aren't just self-hosted — they're designed from the ground up to be modified by AI coding tools. Everything about how the code is organized, named, and documented is aimed at making the next change with Claude Code (or ChatGPT, Cursor, or any other AI tool) as boring and predictable as possible.

This page explains why ARK products are built this way, what the customization philosophy looks like in practice, and where the edges are — the parts you should leave alone.

Why ARK is built for AI customization

Most SaaS tools aren't customizable at all. Most "open source" SaaS alternatives are customizable in theory but have codebases too sprawling or inconsistent for an AI agent to navigate safely.

ARK fills a different gap: small, opinionated products where the entire surface area is small enough that an AI tool can hold the relevant parts in context at once.

In practice, that means:

• Each product's source fits comfortably within a model's context window. Claude Code can load the whole src/ tree for most ARK products in a single session.
• Feature modules are self-contained. Editing the CRM's board code doesn't require touching the automation runner.
• Naming is boring and consistent. Files do what their names say.
• Every product ships a CLAUDE.md that orients the AI on the first read, so you don't have to re-explain the architecture every time.

The result is that asking Claude Code for a reasonable feature change — "add a priority field to deals and show it on the kanban cards" — usually produces a clean, mergeable diff on the first try.

The three customization principles

1. Clean code

Every ARK product is written in TypeScript with strict mode, named exports, small files, and near-zero any. Code you ship yourself on top of this starts from a sane baseline — AI tools suggest edits that match the surrounding style because the surrounding style has a style.

We don't use clever patterns. No meta-programming, no runtime proxies, no magic decorators. When you ask an AI tool to follow a convention, the convention actually exists in the code where it can be imitated.

2. Modular architecture

Each product follows the same layout:

src/
  components/     # Reusable UI primitives
  features/       # Feature modules — one directory per feature
  lib/            # Shared utilities
  pages/          # Top-level routes (or app/ for Next.js-based products)
  theme.css       # Design tokens
supabase/
  schema.sql      # Full schema
  functions/      # Edge Functions
  migrations/     # Additive schema changes

A feature lives in exactly one directory. Want to change how automations work in Track? Open src/features/automations/. Want to change how Comms renders threads? Open src/features/threads/.

This means when you describe a change to an AI tool, you can usually name the exact directory it should touch. Narrow scope produces clean diffs.

3. Comprehensive documentation

Every repo includes:

• CLAUDE.md — conventions, guardrails, and architectural context for AI tools. Read first on every session.
• README.md — what the product is, how to run it, a file map for humans.
• docs/ — longer-form reference that lives next to the code.
• Inline comments where they explain why, not what.

You don't have to read all of it. The AI does, which is the whole point.

What you can modify

Short answer: almost anything.

You bought the source. You can change any feature, replace any dependency, rewrite any component. A partial list of things buyers commonly modify:

• Branding and theme — colors, fonts, logos, the product name displayed in the UI
• Feature behavior — new fields, new views, new filters, new automation actions
• Integrations — Slack, Discord, webhooks, Zapier, custom APIs
• Data model — add columns, tables, and indexes via migrations
• Workflow — change how permissions work for your team, tweak notification rules, add custom dashboards
• Exports — CSV, PDF, markdown exports of whatever data you want
• AI features — hook your own model provider into any feature

See the Example Modifications page for concrete walkthroughs of several of these.

What you shouldn't touch

A small number of files are load-bearing for licensing, security, or traceability. You technically can change them — you own the code — but doing so breaks things in subtle ways.

See Platform Reference → Security Model for the full explanation of what each of these protects.

How this section is organized

If you're new to AI-assisted customization, read these pages in order:

1. Using Claude Code — the recommended tool, how to set it up, and an example workflow.
2. Using ChatGPT & Others — if you already have an AI workflow, how to bring an ARK repo into it.
3. Which Files to Share — a per-product map of which files matter for common types of change.
4. Example Modifications — end-to-end walkthroughs for six common customizations.
5. Best Practices — habits that keep your modifications clean and mergeable when updates arrive.

If you already know what you want to change, jump straight to Example Modifications — one of the walkthroughs is probably close to what you need.