agentleFS
all-source-osall-source-os/all-source/CLAUDE.md

all-source

CLAUDE.md4 starsChanged yesterdayApache-2.0View on GitHub

AllSource Core IS the database. It is a purpose-built Rust event store with full durability: - WAL (Write-Ahead Log): CRC32 checksums, configurable fsync (default 100ms), crash recovery - Parquet: Columnar persistence with Snappy compression, periodic flush - DashMap: In-memory concurrent map for 11.9μs queries and 469K events/sec throughput DO NOT describe Core as "in-memory only", "dumb", "not production-ready", or claim "data is lost on restart." Event data and operational metadata are durable. Users, tenants, API keys, configuration, subscriptions, quotas, and…

  • Deletes or force-pushes
  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    DO NOT: put SDKs in packages/, apps/, or anywhere else.

    line 43
  2. Very specific:

    DO NOT: put shared Rust crates in packages/, apps/, or sdks/.

    line 44
  3. Distinctive:

    No app may COPY, import, or depend on another app's source code

    line 57
  4. Very specific:

    No SDK may import from apps/, crates/, or another SDK

    line 58
  5. Very specific:

    DO NOT: add COPY apps/<other-app>/ to any Dockerfile.

    line 63
  6. Very specific:

    All Core endpoints use the /api/v1/ prefix.

    line 127
  7. Distinctive:

    No Raft, no PostgreSQL in the event path, no multi-leader

    line 164
  8. Distinctive:

    Use judgment, and ask if unsure:

    line 183
  9. Very specific:

    Add agent-parallelism, timeouts and process-ownership when running several agents against this repo at once.

    line 235

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md — AllSource Chronos Monorepo

Critical: Architecture Facts

AllSource Core IS the database. It is a purpose-built Rust event store with full durability:

  • WAL (Write-Ahead Log): CRC32 checksums, configurable fsync (default 100ms), crash recovery
  • Parquet: Columnar persistence with Snappy compression, periodic flush
  • DashMap: In-memory concurrent map for 11.9μs queries and 469K events/sec throughput

DO NOT describe Core as "in-memory only", "dumb", "not production-ready", or claim "data is lost on restart." Event data and operational metadata are durable. Users, tenants, API keys, configuration, subscriptions, quotas, and billing metadata are event-sourced through Core system streams; in-memory maps and service caches are rebuilt from Core.

DO NOT suggest PostgreSQL as a required or primary AllSource store. Current services have zero PostgreSQL dependency: Core is the source of truth for events and operational metadata. The correct way to improve availability is through Core replication (leader-follower, WAL shipping) — not by adding another database.

Repository Structure

See docs/MONOREPO_STRUCTURE.md for full rules. Key directories:

apps/              — Deployable services ONLY
  core/            — Rust event store (AllSource Core) with Prime graph/vector/recall modules
  query-service/   — Elixir/Phoenix API gateway (auth, billing, routing to Core)
  web/             — Next.js frontend dashboard
  mcp-server-elixir/ — Elixir MCP server (separate from Rust MCP Docker binary)
  prime-mcp/       — Rust MCP server for Prime (stdio + HTTP, standalone workspace)
  auth/            — Rust auth service (better-auth + AllSource adapter, standalone workspace)
  chronis/         — Event-sourced task CLI (standalone workspace, excluded from root)
crates/            — Shared Rust library crates (NOT binaries, NOT SDKs)
sdks/              — Client SDKs — ALL languages, NO EXCEPTIONS
  rust/            — Rust SDK
  go/              — Go SDK
  python-client/   — Python SDK
  typescript/      — TypeScript SDK (@allsource/client)
packages/          — Shared non-Rust packages (NOT SDKs, NOT crates)
  ui/              — Shared UI component library
docs/
  proposals/       — Design proposals (e.g., CORE_REPLICATION_DESIGN.md)
  use-cases/       — Use case documents
  current/         — Current architecture docs
deploy/            — K8s manifests, deployment configs
tooling/           — Developer tools (durability tests, etc.)

DO NOT put SDKs in packages/, apps/, or anywhere else. SDKs go in sdks/. DO NOT put shared Rust crates in packages/, apps/, or sdks/. Shared Rust libraries go in crates/.

Isolation (CRITICAL)

Apps, SDKs, and crates are fully isolated. See docs/MONOREPO_STRUCTURE.md Rules 3 and 6 for details.

The dependency graph is strictly one-directional:

apps/ → crates/ → (external)
sdks/ → (external only — SDKs are standalone HTTP clients)
  • No app may COPY, import, or depend on another app's source code
  • No SDK may import from apps/, crates/, or another SDK
  • Each app's Dockerfile references only its own source, plus crates/ stubs if needed
  • Apps that would create cross-contamination in Dockerfiles must be excluded from the root Cargo workspace (workspace.exclude)
  • Apps communicate over the network, not via direct function calls

DO NOT add COPY apps/<other-app>/ to any Dockerfile. DO NOT add new apps to workspace.members if it forces other Dockerfiles to stub them out. DO NOT create dependencies from sdks/ → apps/ or crates/ → apps/.

Service Architecture

Clients → Control Plane / Query Service → Core (Rust, port 3900)
                                           |
                              WAL + Parquet + DashMap
                              (events, system metadata,
                               projections, snapshots, schemas)
  • Core = the database. Source of truth for events, users, tenants, API keys, configuration, subscriptions, quotas, and billing metadata.
  • Query Service = stateless tenant-facing read plane. It separates HTTP queries, Phoenix Channel realtime delivery, analytics endpoints, and rebuildable per-tenant projections over Core events. Caches and read models are disposable; Core remains durable source of truth.
  • Control Plane = public auth, onboarding, billing, and administration layer that persists through Core.
  • PostgreSQL = not required or deployed by current AllSource services.

Per-tenant read-model compute lives in the Query Service, NOT Core

Any per-tenant, user-facing read-model that computes over a tenant's event stream — projections, materialized views, "your projections" dashboards — is a Query Service concern. QS already folds Core's stream into read-models (ProjectionSync → ETS) and terminates the tenant. Do NOT put per-tenant projection compute/state in Core's projection engine (it's on the ingest hot path and is a global, database-internal mechanism). Core's only role here is to store the enabled set as opaque tenant metadata (metadata.projections.enabled) and to serve the tenant's (already tenant-scoped, fail-closed) event stream.

Core's existing global engine projections (entity_snapshots, event_counters, Prime's 9, the embedded demo set) are fine — they are internal, global, not per-tenant. The line: Core may store the enabled set; it may not compute or serve per-tenant projection state.

This is enforced by the tenant-isolation-check gate (tooling/tenant-isolation-check/), which fails if apps/core/src gains per-tenant projection compute (overridable only via an inline // CORE_PROJECTION_OK: <reason> comment). Rationale + the boundary live in docs/proposals/PER_TENANT_PROJECTIONS.md ("Why not Core").

Production Deployment Topology

Everything runs on Fly.io, in the allsource organization. Frontends moved off Vercel on 2026-09-02 (fc601012); docs/runbooks/FLY_FRONTENDS.md is the authority for the frontend half.

Fly appSurfaceDeploy
allsource-coreevent storefly deploy --config apps/core/fly.toml from the repo root
allsource-queryQuery Servicefly deploy --config apps/query-service/fly.toml
allsource-control-planeapi.all-source.xyzfly deploy from apps/control-plane
allsource-authRust auth servicefly deploy --config apps/auth/fly.toml
allsource-primePrime MCPfly deploy --config apps/prime-mcp/fly.toml --dockerfile apps/prime-mcp/Dockerfile from the root
allsource-weball-source.xyz + wwwfly deploy . --config apps/web/fly.toml --remote-only --ha=false
allsource-adminadmin.all-source.xyzfly deploy . --config apps/admin/fly.toml --remote-only --ha=false

Build context differs per app and is not guessable — a wrong context fails the Docker build in a way that reads as a missing file. Follow the table.

Public values are build arguments in each fly.toml; server-only URLs and tokens are Fly secrets or runtime env. Unstoppable Domains DNS points the apex, www, admin and api records straight at Fly.

Core API

All Core endpoints use the /api/v1/ prefix. Key endpoints:

  • POST /api/v1/events — ingest event (returns 200, not 201)
  • GET /api/v1/events/query — query events (returns {"events": [...], "count": N}). Results are ordered by (timestamp, version). Default order is ascending (oldest first); pass order=desc for newest first — e.g. ?entity_id=<id>&limit=1&order=desc fetches the latest event for an entity.
  • GET /api/v1/entities/{id}/state — current state of one entity with a version; no history unless history=true. ETag/304 on If-None-Match.
  • GET /api/v1/event-feed, GET|PUT /api/v1/read-models/{name} — tenant event feed and consumer-folded read-model rows (revision CAS).
  • PUT|GET|DELETE /api/v1/views/{view}, GET /api/v1/views — declarative view definitions; GET /api/v1/views/{view}/entities[/{key}] and /changes?after&wait — latest rows and changes. The Query Service folds the rows; Core stores and serves them (ADR-021, docs/contracts/latest-state/README.md).
  • GET /api/v1/projections — list projections (returns {"projections": [...], "total": N})
  • GET /api/v1/schemas — list schemas
  • GET /health — health check (note: root path, not /api/v1/health)
  • GET /metrics — Prometheus metrics

Core wraps responses in maps ({"events": [...]}, {"projections": [...]}). The Query Service's RustCoreClient unwraps these before passing to controllers.

Query Service Config

  • CORE_URL — Core connection URL (not RUST_CORE_URL — clean env var names, no implementation details)
  • CORE_WS_URL — Core WebSocket URL for real-time streaming
  • Config key in Elixir: :core_url (not :rust_core_url)

Docker Stack

Defined in the wallet project: /Users/decebaldobrica/Projects/alphaSigmaPro/wallet/docker/docker-compose.allsource.yml

Services on supabase_network_alpha-sigma-pro:

  • allsource-core-leader (port 3280 → 3900, replication on 3910)
  • allsource-core-follower-1 (port 3281 → 3900)
  • allsource-core-follower-2 (port 3282 → 3900)
  • allsource-query-service (port 3283 → 3902)
  • allsource-mcp (port 3904)

Building Docker on Apple Silicon: native arm64 only — QEMU cross-compilation to linux/amd64 fails on Erlang NIF.

Scaling Strategy

See docs/proposals/CORE_REPLICATION_DESIGN.md:

  • Leader-follower replication via WAL shipping
  • Query Service routes writes to leader, reads round-robin across followers
  • No Raft, no PostgreSQL in the event path, no multi-leader

Git Workflow

Default: commit direct to main. Do NOT create feature branches or open pull requests for routine work.

This repo is maintained by a single owner who reviews changes at commit time, not PR time. Going through feature-branch-and-PR for docs, fixes, and features adds rounds without adding review value. Branching/PR flows also surface a recurring local HEAD branch-slip bug that has cost time debugging git mechanics instead of shipping.

Rules

  • Default workflow: git status → git add <paths> → git commit → git push origin main. No branches. No gh pr create.
  • Always verify git branch --show-current before committing. The branch-slip bug can flip HEAD between tool calls. If you aren't on main, fix it before staging.
  • Always run git status before committing. Include related dirty files in the same commit or flag them to the user. Never leave the tree messy after a push.
  • NEVER force-push main. Force-pushing a feature branch to update a PR was fine under the old flow; force-pushing main is not. If you need to rewrite history, stop and ask.
  • NEVER push --tags or run git tag without the user's explicit go-ahead. Releases are the one place where "user manually pushes" still applies — see .claude/skills/chronos-release/SKILL.md and the release discipline note in MEMORY.md.
  • NEVER bypass hooks or signing. No --no-verify, no -c commit.gpgsign=false. If a hook fails, fix the underlying issue.

Exceptions — when a branch or PR IS still the right call

Use judgment, and ask if unsure:

  • User explicitly asks for a PR — honor the request.
  • External contributions from anyone other than the repo owner.
  • Experimental / WIP work the user wants reviewable without it landing on main.
  • Releases — the release flow still runs on main directly (see the release skill), but tag push requires explicit user confirmation. Tag naming is scoped by release scope: full-monorepo releases use v<VERSION>; SDK-only releases use sdk-<lang>-v<VERSION> (e.g. sdk-rust-v0.19.0) so per-SDK versions don't collide with Core/QS versions.

What this replaces

Any advice from prior sessions or auto-memory entries about "push to a feature branch first" or "open a PR before merging" no longer applies for routine work on this repo. The main-branch-first workflow is the authoritative default.

Planning

Planned work runs as one ritual-full flow: Think, Spec, Plan, Build, Review, Ship, Reflect. It runs on a Chronis epic whose ritual-* lines name each step's file. Flow: .claude/skills/ritual-full/SKILL.md. Guide: https://github.com/decebal/decebal-claude-skills/blob/main/docs/ritual-zero-to-hero.md.

  • Ship follows Git Workflow. It opens a PR only when the user asked for one (see Exceptions above); otherwise it commits and pushes to main.
  • Design approval is the user's decision. Approve only after the user tells you to approve in the conversation, and quote that instruction in your report. Never approve on your own initiative.
  • Approve with cos ritual approve <epic> <design> --by "<name>" --review <path> --yes, or cn approve <epic> without cos. --yes needs decebal/chief-of-staff-v2#23.
  • A bug with a clear reproduction skips Think and Spec and goes through systematic-debugging.
  • .claude/skills/ritual* and semantic-isa are vendored. Do not edit them here; change them upstream in decebal/decebal-claude-skills.

Rules

This repo follows the portable rule set published at decebal-claude-skills → rules/. Each rule carries the incident that produced it; that is the load-bearing part.

Loaded by reference, not by copy. Install once per machine:

git clone https://github.com/decebal/decebal-claude-skills
mkdir -p ~/.claude/rules
cp decebal-claude-skills/rules/*.md ~/.claude/rules/

then @-import the subset you want from ~/.claude/CLAUDE.md. Copying the rule text into this repo would fork it, and a rule written twice drifts in one copy without anyone noticing which — that is what the single source prevents.

The subset that applies here

RuleCovers
git-disciplineOne PR = one commit, merged by rebase. Dead-branch liveness check before the first commit. Never push to the trunk
evidence-disciplineCheck the destination before trusting an absence; read runtime state, never guess it
definition-of-doneEnd-to-end or not done; size is never a reason to split
estimationNever estimate in time; rock / sand / water is confidence, not size
commentsWhat a comment must earn; never narrate the fix
anti-slopReport findings, don't perform them
pr-evidence-reportThe HTML report a PR ships: claim → evidence → limits, screenshots with provenance, SHA-anchored before/after, copy blocks with a Pass line
documents-not-artifactsDeliverables are versioned documents under docs/, never hosted pages

Add agent-parallelism, timeouts and process-ownership when running several agents against this repo at once.

Merge settings, already enforced on this repo

Rebase-only — allow_squash_merge=false, allow_merge_commit=false, allow_rebase_merge=true — with delete_branch_on_merge=true.

A PR therefore cannot merge until its branch is a single commit. Collapse before review:

git reset --soft "$(git merge-base origin/main HEAD)"
git commit -F <message-file>
git diff <old-head> HEAD          # MUST be empty — that is the proof
git push --force-with-lease=refs/heads/<branch>:<old-head> origin HEAD:<branch>

Pin the lease to the old head you actually reviewed. The bare form does not refuse when someone else pushed in between; the pinned form does.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.