Command Palette

Search for a command to run...

Arbtr

Command Palette

Search for a command to run...

Arbtr Architecture

Dogfooding

We use Arbtr to document Arbtr. Here are our own architectural decisions.

This page documents Arbtr's own architectural decisions. It's not just documentation—these are real decisions in our Arbtr instance.

We practice what we preach. Every significant technical choice is recorded, with context, positions considered, and rationale. The relationship graph shows how these decisions connect.

i

Live data

These decisions are seeded in the arbtr-architecture team. If you're running Arbtr locally, run the seed script to populate this data.

The Decision Graph

                              ┌─────────────────────┐
                              │    Use Next.js      │ ◀─────────────────────────────┐
                              │      [Anchor]       │                               │
                              └──────────┬──────────┘                               │
                    ┌─────────────┬──────┴──────┬─────────────┐                     │
                    ▼             ▼              ▼             ▼                     │
          ┌─────────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐      │
          │  Use Supabase   │ │  Tailwind   │ │  App Router  │ │  ReactFlow   │      │
          │    [Anchor]     │ │ [Committed] │ │ [Committed]  │ │  [Standard]  │      │
          └────────┬────────┘ └─────────────┘ └──────────────┘ └──────────────┘      │
                   │                                                                 │
                   ▼                                                                 │
          ┌─────────────────┐                ┌──────────────────┐                    │
          │      RLS        │ ──enables───▶  │  Multi-tenancy   │                    │
          │    [Anchor]     │                │    [Anchor]      │                    │
          └─────────────────┘                └──────────────────┘                    │
                                                                                     │
          ┌─────────────────┐                ┌──────────────────┐                    │
          │   BYOK for AI   │ ◀─depends───── │   Magic Paste    │                    │
          │   [Committed]   │                │   [Committed]    │                    │
          └─────────────────┘                └──────────────────┘                    │
                                                                                     │
          ┌─────────────────────┐                                                    │
          │ Relationships > Votes│                                                   │
          │      [Anchor]        │ ◀──derived_from────┬─────────────────────────────│
          └──────────┬──────────┘                     │                              │
                     │                                │                              │
          ┌──────────▼──────────┐        ┌───────────┴─────────┐                     │
          │   Graph-first nav   │        │    No arg scores    │                     │
          │    [Committed]      │        │    [Committed]      │                     │
          └─────────────────────┘        └─────────────────────┘                     │
                     │                                                               │
                     └───────────────────────────────────────────────────────────────┘
                                                                depends_on

Interactive Graph Coming Soon

The full interactive decision graph will be embedded here. For now, explore the decisions below.

Technology Stack

Use Next.js as the web framework

Anchor

Full-stack React with SSR, API routes, and App Router

Approved

Use Supabase for database and auth

Anchor

PostgreSQL with real-time, auth, and RLS in one package

depends_on: Use Next.js
Approved

Use Tailwind CSS with shadcn/ui

Committed

Utility-first CSS with copy-paste component ownership

depends_on: Use Next.js
Approved

Use TypeScript in strict mode

Anchor

Full type safety, no any unless documented

constrains: All code
Approved

Use App Router over Pages Router

Committed

React Server Components for better performance

depends_on: Use Next.js
Approved

Architecture

Team-based multi-tenancy with slugs

Anchor

All data scoped to teams, human-readable URLs

Approved

Row Level Security for data isolation

Anchor

Database-enforced team isolation, defense in depth

depends_on: Use Supabaseenables: Team-based multi-tenancy
Approved

BYOK (Bring Your Own Key) for AI

Committed

Users provide their own API keys, no AI billing complexity

Approved

Client-side graph rendering with ReactFlow

Standard

Interactive node graph for decision visualization

depends_on: Use Next.js
Approved

Product Philosophy

Relationships over voting as core value

Anchor

The graph of dependencies matters more than vote counts

Approved

Graph-first navigation

Committed

Users navigate through the graph, not list views

derived_from: Relationships over voting
Approved

Magic Paste for frictionless input

Committed

AI extracts decisions from unstructured text

depends_on: BYOK for AI
Approved

One-way Git sync (publish only)

Standard

Arbtr is the editor, Git is the archive

Approved

No argument quality scores

Committed

Check completeness, never rate quality

derived_from: Relationships over voting
Approved

Running the Seed Script

To populate these decisions in your local Arbtr instance:

# Set your Supabase credentials

export NEXT_PUBLIC_SUPABASE_URL="your-url"

export SUPABASE_SERVICE_ROLE_KEY="your-key"

# Run the seed script

npx tsx scripts/seed-arbtr-architecture.ts

This creates the arbtr-architecture team with all 14 decisions and their relationships.

Why Document Our Own Decisions?

We document our own architectural decisions for three reasons:

  1. Dogfooding

    Using Arbtr to build Arbtr exposes friction points and missing features. If it's painful for us, it's painful for users.

  2. Demonstration

    Real decisions are more compelling than hypotheticals. These show exactly how relationships, domains, and importance levels work.

  3. Transparency

    Open-source means open decisions. Users can see not just what we built, but why we made the choices we did.

Previous

RFC Process

Back to start

Manifesto
    Arbtr Architecture | Arbtr Docs