Locara

17 — Repository Layout

Locara is a monorepo. The framework, runtime, CLI, registry, components, reference apps, and website all live together because they share schemas (manifest, capability) and evolve in lockstep.

Top-level structure

locara/
├── README.md                       # The public-facing thesis + quickstart
├── LICENSE                         # Apache 2.0
├── CONTRIBUTING.md                 # How to contribute
├── CODE_OF_CONDUCT.md
├── package.json                    # Bun workspace root
├── bun.lockb                       # Bun lockfile
├── biome.json                      # lint + format config
├── .mise.toml                      # tool version pinning
├── Cargo.toml                      # Rust workspace root
├── rust-toolchain.toml
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                  # Test, lint, typecheck on PR
│   │   ├── publish-app.yml         # CI build pipeline for publishing apps
│   │   ├── release.yml             # Locara framework releases
│   │   └── nightly.yml             # Nightly model + tool registry rebuilds
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
│
├── crates/                         # Rust crates — libraries that apps link
│   ├── locara-core/                # capability enforcement, inference (llama.cpp)
│   ├── locara-storage/             # SQLite + sqlite-vec adapter
│   ├── locara-models/              # content-addressed model fetch + cache
│   ├── locara-tools/               # Wasmtime + WASI tool runtime
│   ├── locara-runtime/             # Tauri plugin orchestration; framework glue
│   └── locara-cli/                 # the `locara` developer binary
│
├── packages/                       # TypeScript packages
│   ├── sdk/                        # @locara/sdk
│   ├── components/                 # @locara/components (shadcn-style source registry)
│   ├── manifest/                   # @locara/manifest (JSON schema + TS types)
│   └── test/                       # @locara/test (test helpers)
│
├── apps/                           # Reference apps — each is a standalone Tauri app
│   ├── transcribe/                 # uses Locara framework via crate + npm deps
│   └── docvault/
│
├── registry/                       # Registry data + tools (separate Git repo possible)
│   ├── apps/                       # App manifests (one JSON per published app version)
│   ├── models/                     # Curated model manifests
│   ├── tools/                      # Curated tool manifests + wasm sources
│   └── components/                 # Curated component registry manifests
│
├── website/                        # locara.app — the static website
│   ├── pages/                      # Astro/HTML pages
│   ├── components/                 # Site components
│   └── content/                    # Blog, ADRs, manifesto, docs in markdown
│
├── spec/                           # YOU ARE HERE — the spec docs
│   ├── README.md
│   ├── 00-overview.md
│   └── ...
│
├── notes/                          # Research notes (companion folder)
│   └── ...
│
└── docs/
    └── adr/                        # Architecture Decision Records
        ├── 0001-pick-tauri.md
        ├── 0002-mlx-vs-llamacpp.md
        └── ...

Rust crates (crates/)

locara-core

The heart. Inference engines, capability enforcement, model loading.

locara-core/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── inference/                  # llama.cpp + MLX backends
│   │   ├── llamacpp.rs
│   │   ├── mlx.rs
│   │   └── router.rs               # Picks backend based on hardware
│   ├── capability/                 # Capability enforcement
│   │   ├── manifest.rs
│   │   ├── enforcer.rs
│   │   └── scope.rs
│   ├── modality/                   # Modality expansion logic
│   │   └── expander.rs
│   └── error.rs
└── tests/

Depends on: llama-cpp-2 (or our binding), mlx-rs (when integrated), serde, tokio.

locara-storage

SQLite + sqlite-vec + zvec adapter.

locara-storage/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── sqlite.rs                   # Connection pooling, query helpers
│   ├── vec/
│   │   ├── sqlite_vec.rs
│   │   └── zvec.rs
│   ├── schema.rs                   # Schema parsing + diffing
│   └── migration.rs                # Migration runner
└── tests/

locara-models

Model registry client, content-addressed fetch, cache management.

locara-models/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── registry.rs                 # Talks to Locara registry API
│   ├── fetch.rs                    # Resumable downloads, SHA verification
│   ├── cache.rs                    # Local cache management, refcount-based GC
│   └── manifest.rs                 # Locara model manifest types
└── tests/

locara-tools

Wasmtime + WASI tool runtime.

locara-tools/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── runtime.rs                  # Wasmtime engine, store mgmt
│   ├── imports.rs                  # WASI import construction per tool capability
│   ├── cache.rs                    # Tool wasm cache
│   └── invoke.rs                   # Tool invocation entry point
└── tests/

locara-runtime

Per-app lifecycle. Sits above core/storage/models/tools and below the Tauri shell.

locara-runtime/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── lifecycle.rs                # Install / launch / update / uninstall
│   ├── ipc.rs                      # Tauri command dispatch
│   ├── plugin/                     # Tauri plugins exposing locara primitives
│   │   ├── llm.rs
│   │   ├── transcribe.rs
│   │   ├── ocr.rs
│   │   ├── embed.rs
│   │   ├── db.rs
│   │   ├── tools.rs
│   │   └── fs.rs
│   └── error.rs
└── tests/

locara-cli

The locara binary.

locara-cli/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── cmd/
│   │   ├── init.rs
│   │   ├── dev.rs
│   │   ├── test.rs
│   │   ├── verify.rs
│   │   ├── build.rs
│   │   ├── publish.rs
│   │   ├── doctor.rs
│   │   ├── simulate.rs
│   │   ├── add.rs                  # locara add (component)
│   │   ├── model.rs                # locara model {add, list, verify}
│   │   └── db.rs                   # locara db {generate-types, migrate, diff}
│   └── templates/                  # Embedded init templates
│       ├── blank/
│       ├── transcribe/
│       ├── docvault/
│       └── chat/
└── tests/

TypeScript packages (packages/)

Standard Bun workspace (per ADR 0013 and 49-toolchain.md).

@locara/sdk

packages/sdk/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── llm.ts
│   ├── embed.ts
│   ├── transcribe.ts
│   ├── vlm.ts
│   ├── ocr.ts
│   ├── db.ts
│   ├── tools.ts
│   ├── fs.ts
│   └── audio.ts
└── tests/

@locara/components

shadcn-style copy-in registry. The package itself is a small CLI helper; the actual components are served as a registry.

packages/components/
├── package.json
├── registry.json                   # Component manifest
└── components/
    ├── chat/
    │   ├── chat.tsx
    │   ├── chat.locara.json        # component metadata
    │   └── README.md
    ├── doc-dropzone/
    ├── transcript-stream/
    └── ...

@locara/manifest

packages/manifest/
├── package.json
├── src/
│   ├── index.ts                    # TS types
│   ├── schema.json                 # JSON Schema (used by editors)
│   └── validate.ts
└── tests/

@locara/test

packages/test/
├── package.json
├── src/
│   ├── index.ts
│   ├── runtime.ts                  # Headless Locara runtime for testing
│   ├── capability-scenarios.ts
│   └── matchers.ts
└── tests/

Reference apps (apps/)

Each is a complete, standalone Tauri application that ships as both reference and product. It depends on Locara’s framework crates + npm packages.

apps/transcribe/
├── locara.json                     # Locara manifest
├── package.json                    # standard Tauri/npm
├── src-tauri/                      # standard Tauri Rust side
│   ├── Cargo.toml                  # depends on locara-runtime, etc.
│   ├── tauri.conf.json
│   └── src/main.rs                 # boilerplate that wires up Locara plugins
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── lib/
│   └── components/ui/
├── db/
│   ├── schema.sql
│   └── migrations/
├── tests/
├── public/
├── screenshots/
└── README.md

Registry data (registry/)

Could be a separate Git repo (likely will be, for separate access controls). Holds:

registry/
├── apps/
│   └── kingtongchoo/transcribe/
│       ├── 0.1.0.json
│       └── 0.1.1.json
├── models/
│   ├── qwen2.5-3b-instruct-q4.json
│   └── whisper-large-v3-q4.json
├── tools/
│   └── ocr.json
└── components/
    └── chat.json

A static site rendered from this Git repo serves as the registry frontend. Any change is a PR; review pipeline runs in GitHub Actions.

Website (website/)

website/
├── package.json (Astro / Next.js)
├── public/
├── src/
│   ├── pages/
│   │   ├── index.astro
│   │   ├── docs/
│   │   ├── blog/
│   │   ├── apps/
│   │   └── adr/
│   ├── components/
│   └── content/
└── astro.config.ts

Content (blog posts, ADRs, manifesto, docs) lives in markdown alongside.

ADRs (docs/adr/)

Each numbered ADR captures one decision:

docs/adr/
├── README.md                       # Index of ADRs
├── 0001-pick-tauri.md
├── 0002-mlx-vs-llamacpp-default.md
├── 0003-shadcn-style-component-distribution.md
├── 0004-modalities-as-first-class.md
├── 0005-cii-builds-no-user-uploads.md
└── ...

ADR template:

# 0001: Pick Tauri over Electron

Status: Accepted
Date: 2026-04-30
Deciders: kingtongchoo

## Context
[What problem are we solving?]

## Decision
[What did we choose?]

## Consequences
[What follows from this?]

## Alternatives considered
[What else, why not?]

## References
[Notes, papers, prior art]

When a (open) in the spec is resolved, an ADR is added.

Build orchestration

  • Rust workspace: cargo build --workspace.
  • Node workspace: bun run build (turbo-style if needed).
  • Cross: A single make or top-level script orchestrates.

License headers

All source files include:

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 The Locara Project

Open questions

  • (open) Single repo or split? Pro single: easier coordination. Con single: large clone, all-or-nothing access. v1: single. Future: registry data + apps move out.
  • (open) Turborepo / Nx for build orchestration? Probably not needed; pnpm workspaces + cargo workspace + a few scripts is enough.
  • (open) Should apps/transcribe and apps/docvault be in this repo or separate? In this repo for v1 (tight coordination); split out later when stable.

Cross-references