Metadata-Version: 2.3
Name: mathen
Version: 0.0.2
Summary: Evidence-backed architecture knowledge base and CLI
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Mathen

Mathen is an evidence-backed, temporal knowledge graph for software
architecture.

It studies software systems from two complementary directions:

1. **Analysis:** translate systems into reusable architectural features,
   state models, invariants, trade-offs, and mathematical views.
2. **Synthesis:** compose those features under explicit requirements and
   constraints to explore candidate architectures for new systems.

Mathen treats architecture as an evolving network rather than a static list of
products. Systems acquire new features, dependencies, relationships, and
community memberships over time. New systems are often formed by recombining
existing ideas under a new workload, deployment boundary, hardware context, or
set of operational constraints.

> **Mathen turns software architecture into a time-aware, evidence-backed,
> mathematically informed intermediate representation that can be compared,
> composed, and validated.**

## Why Mathen exists

Architecture knowledge is scattered across source code, design documents,
papers, benchmarks, protocol specifications, and operational experience. This
makes it difficult to answer questions such as:

- Which design properties do SQLite and DuckDB share, and where do they
  diverge?
- How does PostgreSQL connect relational databases, extensibility, indexing,
  replication, and domain-specific extensions?
- Which existing structures are composed by Supabase or Firecracker?
- Which properties are preserved when two architectural patterns are combined?
- What new conflicts, assumptions, and costs appear in the combination?
- How did a system's architecture and relationships change between versions?

Mathen makes these questions machine-readable without reducing architecture to
ungrounded labels or a single oversimplified definition.

## Project status

This repository is a research prototype. Architecture Cards are structured,
evidence-backed models, not automatic formal proofs of the corresponding
implementations.

Source code and the browser client are available in the
[Mathen GitHub repository](https://github.com/Xuepoo/mathen).

## The core model

Mathen represents a system through several complementary views:

```text
System and version
├── data model and types
├── state space and transitions
├── operations and composition laws
├── dependency and causality graph
├── consistency and convergence model
├── storage and execution model
├── isolation and security boundary
├── failure and recovery model
├── resource, performance, and cost model
└── evolution, migration, and composition history
```

No single mathematical structure is expected to explain an entire system. A
mathematical view is useful only when it answers a concrete question and states
its assumptions. Depending on the question, a view may use:

| Architecture question           | Candidate mathematical view                |
| ------------------------------- | ------------------------------------------ |
| What are the data and objects?  | Sets, types, algebraic data types          |
| How are objects related?        | Graphs, DAGs, partial orders               |
| How does the system evolve?     | State machines, transition systems         |
| Which operations compose?       | Monoids, algebras, compositional semantics |
| Does state converge?            | Semilattices, monotone systems             |
| Is an optimization transparent? | Refinement, simulation, bisimulation       |
| How do failures affect service? | Probability, queueing, reliability models  |
| How are resources bounded?      | Complexity and cost models                 |

These are candidate abstractions, not automatic proofs. Each claim is labeled
as a `fact`, `inference`, `hypothesis`, or `analogy`, and remains connected to
its evidence and scope.

## A temporal, multi-layer architecture graph

The long-term knowledge graph contains more than software names. It can include
systems, versions, features, primitives, mathematical models, programming
languages, operating systems, protocols, organizations, evidence, and candidate
architectures.

Relationships are typed rather than collapsed into a generic similarity edge:

```text
implements       uses              extends
composes         resembles         influenced-by
depends-on       conflicts-with    optimizes-for
evolves-to       verified-by       constrained-by
```

This distinction matters. Historical influence needs historical evidence;
structural similarity can be inferred from architecture analysis; a dependency
should be supported by implementation or documentation evidence.

The graph is temporal:

```text
version A ──evolves-to──> version B ──adds──> feature C
       │                         └──uses──> primitive D
       └──belongs-to──> community E
```

It can represent the first appearance of a feature, version-specific changes,
new dependencies, community membership, composition lineage, and candidate
architectures that have not yet been implemented. Systems can belong to many
overlapping communities: PostgreSQL can connect relational databases, MVCC,
database extensibility, geospatial data, vector search, replication, and
backend platforms at the same time.

## From analysis to synthesis

Mathen uses a staged workflow:

```text
source code / documents / papers / experiments
                         ↓
                 fixed evidence and provenance
                         ↓
             deterministic repository observations
                         ↓
       semantic features, mathematical views, trade-offs
                         ↓
             reviewed temporal architecture graph
                         ↓
        constraint-based comparison and composition
                         ↓
             prototype, benchmark, and failure tests
```

When exploring a new architecture, Mathen records more than its input
features:

```text
inputs
new constraints
target workload
preserved properties
introduced conflicts
new trade-offs
unverified assumptions
validation plan
```

Architecture synthesis is not feature shopping. For example, combining
embedded execution, columnar vectorization, append-only recovery, and
content-addressed snapshots requires checking the write model, transaction
boundary, recovery protocol, update pattern, and storage costs.

## Representative examples

The current cards and repository analyses use systems that expose different
architectural patterns:

| System      | Reusable structure being studied                                        |
| ----------- | ----------------------------------------------------------------------- |
| Git         | Immutable content-addressed objects, mutable references, causal history |
| SQLite      | Embedded execution, layered storage, atomic commit, WAL snapshots       |
| DuckDB      | Embedded analytical execution, columnar data, vectorized operators      |
| PostgreSQL  | Extensible relational engine, MVCC, process isolation, extensions       |
| Kafka       | Durable append-only logs, ordered offsets, replay-oriented consumption  |
| Kubernetes  | Declarative state, reconciliation loops, control-plane convergence      |
| Firecracker | Minimal virtual machine model, KVM isolation, event-driven VMM          |
| Supabase    | Database-centered platform composition, API, auth, and data policy      |

These are starting points for extracting structures that can be compared across
databases, distributed systems, operating systems, runtimes, network protocols,
compilers, media systems, and programming languages. They are not claimed to
be complete formal models or evidence of historical influence.

## Evidence and review boundary

Mathen separates observations, interpretations, and reviewed knowledge:

```text
data/systems/       reviewed canonical Architecture Cards
data/drafts/        unreviewed generated cards
data/modeling/      fixed-commit evidence bundles and prompts
data/analyses/      ignored deterministic repository reports
```

The project follows these rules:

1. Extract observable facts before assigning mathematical terminology.
2. Cite primary evidence wherever possible.
3. Give every mathematical view a question and assumptions.
4. Record benefits, costs, preconditions, failure modes, and counterexamples.
5. Keep structural similarity separate from historical influence.
6. Never let LLM output overwrite reviewed cards.
7. Treat candidate compositions as hypotheses until implemented or validated.

An LLM proposes abstractions and comparisons; deterministic tools provide
provenance and observations; schema and semantic validation constrain output;
human review decides what becomes canonical.

## Current implementation

The repository currently provides:

- a versioned Architecture Card schema and semantic validator;
- a representative repository catalog across databases, logs,
  orchestration, isolation, virtualization, networking, compilers, media, and
  backend platforms;
- fixed-commit repository analysis with Git and GitHub archive transports;
- deterministic repository observations for source structure, build surfaces,
  and navigation signals without assigning semantic facts;
- portable modeling bundles and a provider-neutral OpenAI-compatible LLM
  adapter;
- a bounded composition candidate explorer whose results remain
  `proven: false`;
- a Cloudflare-first Hono Worker API backed by D1;
- a Vite browser client for browsing reviewed architecture cards;
- read-only API queries for source-card-owned feature relations and composition
  proposals;
- a read-only stdio MCP server with filesystem and API backends;
- optional Cloudflare Turnstile protection, signed browser access sessions,
  service-token API access, and per-IP limits;
- explicit separation between reviewed cards, drafts, and modeling evidence.

The canonical tree currently contains 219 reviewed cards. The representative
repository manifest contains 62 entries, all with matching canonical cards.

The current knowledge graph is intentionally relational and small. D1 is the
canonical structured store. Vectorize is an optional rebuildable semantic
index, and a dedicated graph database remains a future adapter rather than a
first-milestone dependency.

## Quick start: Python card tooling

```bash
uv tool install mathen
mathen version
mathen config init
uv run mathen validate
uv run mathen list
uv run mathen show git
```

The CLI supports a cross-platform TOML configuration under the user's standard
configuration directory. Configure paths and an OpenAI-compatible LLM endpoint
with `mathen config set`; see [`docs/configuration.md`](docs/configuration.md).
The current package release is `v0.0.2`. Pushing a matching version tag builds
and publishes the Python distributions to PyPI through the
`PYPI_API_TOKEN` GitHub Actions secret.

For an installed CLI, download the reviewed cards before browsing them:

```bash
mathen data sync
mathen data status
mathen doctor
mathen mcp path
mathen mcp check
mathen list
mathen show git
```

Analyze the representative repository catalog into reviewable draft cards:

```bash
uv run mathen analyze data/repositories/representative.json \
  --cache-dir /tmp/mathen/repos \
  --output-dir data/drafts
```

The command uses shallow, blob-filtered Git checkouts and reads tracked tree
metadata without materializing the full worktree. Existing cached checkouts are
reused by default; pass `--refresh` only when a network update is required.
The source cache is not committed. Reports are written to the ignored
`data/analyses/` directory, while draft cards are written to `data/drafts/` and
must be reviewed before promotion to `data/systems/`.

When GitHub's Git transport is unavailable, use the source archive transport:

```bash
uv run mathen analyze data/repositories/representative.json \
  --transport archive \
  --continue-on-error
```

Prepare evidence bundles for LLM-assisted architecture modeling:

```bash
uv run mathen prepare-modeling --write-prompts
```

This writes fixed-commit JSON bundles to `data/modeling/` and portable prompts
to `data/modeling/prompts/`. The bundle is the input to the semantic modeling
step; its output remains a draft until evidence and claims are reviewed.

Run the provider-neutral adapter against those bundles:

```bash
export OPENAI_API_KEY=...
export MATHEN_LLM_MODEL=gpt-4.1-mini
uv run mathen model --system git
```

Generated cards are written under `data/drafts/llm/`. The adapter checks card
semantics and prevents model output from introducing or changing evidence
records. Configure an OpenAI-compatible endpoint with `MATHEN_LLM_BASE_URL`,
or use the explicit `--api-key`, `--model`, and `--base-url` flags. See
[`docs/llm-modeling.md`](docs/llm-modeling.md) for the full workflow.

## Quick start: Cloudflare application

Prerequisites: Bun and Wrangler.

The repository also provides a `just` command layer for the common local
workflows below. The existing `bun` and `uv` commands remain the underlying
implementation commands.

```bash
bun install
just db-reset
just dev
```

The local API runs at `http://localhost:8787` and the Vite client runs at
`http://localhost:5173`. The Vite development server proxies `/api` requests
to the Worker.

The application deliberately uses D1 as the source of truth. Vectorize is an
optional search index and is not required for local structured browsing. A
local MCP server exposes read-only system, feature, and modeling-bundle tools;
see [`docs/mcp.md`](docs/mcp.md). Set `MATHEN_API_URL=http://localhost:8787/api`
to make it read reviewed data and modeling bundles through the Hono/D1 API;
without that variable it uses the local filesystem. A future hosted MCP server
can call the same API and submit reviewed Architecture Cards generated from a
local repository.

Run the standard checks:

```bash
just check
```

Run `just` or `just --list` from the repository root to see all available
recipes. Useful focused commands include `just python-check`, `just api-test`,
`just typescript-check`, `just build`, and `just mcp`.

The Python development toolchain, including Ruff, is declared in
`pyproject.toml` and installed by `uv sync --locked`.

## Quick start: MCP

Start the local read-only MCP server from the repository root:

```bash
bun run mcp
```

By default it reads the local filesystem. To read reviewed systems and fixed
modeling bundles through the Hono/D1 API instead:

```bash
MATHEN_API_URL=http://localhost:8787/api bun run mcp
```

The server exposes `list_systems`, `get_system`, `search_features`,
`list_feature_relations`, and `get_modeling_bundle`. API mode does not expose
drafts; filesystem mode exposes them only when explicitly requested. See
[`docs/mcp.md`](docs/mcp.md).

## Repository layout

```text
docs/                       Research and modeling documentation
schemas/                    JSON Schema for architecture cards
data/systems/               Evidence-backed system cards
data/repositories/          Representative repository analysis catalog
data/drafts/                Unreviewed generated Architecture Cards
data/modeling/              Fixed-commit modeling bundles
data/analyses/              Ignored deterministic inspection reports
src/mathen/                 Validation, analysis, and LLM tooling
tests/                      Unit tests
apps/api/                   Hono Worker and D1 migrations
apps/web/                   Bun/Vite browser client
apps/mcp/                   Read-only stdio MCP server
```

## Design principles

1. **Evidence before abstraction**: every non-trivial claim should link to a
   primary source or be explicitly marked as an inference.
2. **Views rather than one essence**: a system may have several valid
   mathematical views, each tied to a question and assumptions.
3. **Claims have boundaries**: benefits, costs, preconditions, and counter-
   examples are stored together.
4. **Structure is reusable**: cards describe transferable features rather than
   only product-specific descriptions.
5. **Validation precedes automation**: LLM output must pass schema and semantic
   checks before entering the knowledge base.

## Roadmap

The project is developed in stages:

1. **Representation and evidence:** stabilize Architecture Cards and review
   rules.
2. **Assisted extraction:** turn fixed-commit evidence into constrained drafts.
3. **Application and retrieval:** provide D1, API, browser, semantic search,
   and MCP access.
4. **Temporal and relational graph:** model versions, evolution, communities,
   composition, constraints, and evidence lineage.
5. **Architecture synthesis:** query requirements, generate candidate
   compositions, expose conflicts, and validate candidates with prototypes,
   benchmarks, and failure tests.

The long-term goal is a disciplined intermediate layer between implementation
and design reasoning:

```text
existing systems → reusable architectural structures → candidate designs
```

## Non-goals

Mathen does not currently aim to:

- automatically prove that an implementation satisfies a mathematical model;
- claim originality from structural similarity alone;
- replace source review, experiments, benchmarks, or human architecture
  judgment;
- treat every mathematical analogy as a formal equivalence;
- operate a general-purpose graph database before relational query patterns
  demonstrate that it is necessary.

## Documentation

- [`docs/user-manual.md`](docs/user-manual.md) — schemas, data flow, and
  operating procedures
- [`docs/catalog.md`](docs/catalog.md) — long-term Mathen catalog backlog
- [`docs/vision.md`](docs/vision.md) — project motivation and modeling views
- [`docs/methodology.md`](docs/methodology.md) — evidence and validation rules
- [`docs/repository-catalog.md`](docs/repository-catalog.md) — repository
  analysis policy and catalog
- [`docs/llm-modeling.md`](docs/llm-modeling.md) — constrained LLM modeling
- [`docs/mcp.md`](docs/mcp.md) — read-only agent access
- [`docs/hosting.md`](docs/hosting.md) — Cloudflare deployment boundary
- [`docs/roadmap.md`](docs/roadmap.md) — staged implementation plan

## License

See [`LICENSE`](LICENSE).
