Familiar

I built this because I wanted a locally-hosted project management suite. I've been starting new projects with a PM perspective. That means creating and saving foundational documentation, such as project charters and SOPs. I wanted something to view project progress at a glance: working items, risks, decisions, relationships, and recent activity. This app has increased my productivity tenfold.

Familiar Engineering Decisions and Qualification

This document summarizes Familiar's engineering and delivery approach as of October 10, 2026. It covers the application's architecture, development and distribution decisions, CI/CD pipeline, and qualification methodology.

Engineering Decisions

Application Structure

• Familiar is a local-first desktop workspace built with React, strict TypeScript, Tauri 2, Rust, and SQLite. Production starts with an empty workspace; sample data is confined to development.
• The UI uses a typed repository for projects, records, workflows, search, relationships, settings, and exports. SQL and schema migrations live in src/data.
• The shared records table provides identity and project scope. Typed tables hold milestone, work item, risk, decision, document, and design-asset details. Foreign keys and transactions protect project boundaries and consistent updates.
• The native Tauri app owns a mutex-protected rusqlite connection, uses SQLite WAL, and stores its database under the platform app-data directory. The browser development mode uses SQL.js with IndexedDB and a Web Lock. These are separate stores, not synchronized copies.
• No database server, login, analytics, telemetry, or cloud service is part of the current native app. GitHub integration is an interface and local reference feature; synchronization is not implemented.
• Schema changes use ordered migrations. Shipped migrations are immutable; later changes add a migration. Startup refuses databases created by newer schemas.
• Backups and imports use explicit user actions and validation. Failed imports roll back transactionally. The native live database path is managed by the application; arbitrary path changes and background repository modification are not supported.

Preview Delivery Decisions

• The approved recipient preview direction is an arm64 Tauri app with native SQLite, built and inspected by hosted macOS CI.
• Initial delivery is a directly shared, ad-hoc-signed qualification artifact. This signature provides integrity, not Apple publisher authentication or notarization. Expected Gatekeeper handling is a per-app exception; global Gatekeeper changes and quarantine removal are excluded.
• Candidate replacement is manual and limited to tested compatible versions. There is no automatic updater or automatic GitHub Release publication in the current qualification workflow.
• Real-data handoff depends on native recovery, startup safeguards, compatible replacement and rollback, and target-device acceptance. CLI/Kuri runtime and VPS work are outside this approved delivery architecture.

CI/CD Design

Familiar's Tauri preview qualification workflow separates cross-platform checks from Apple Silicon build qualification.

1. Linux validation: Uses a clean checkout and locked npm dependencies to run typecheck, lint, unit and distribution tests, Python bundle checks, browser tests, and the production preview smoke test. It verifies those checks did not modify tracked or untracked inputs.
2. macOS arm64 qualification: Runs after Linux validation on an explicit macOS 26 runner and asserts the runner architecture. It uses pinned Node and Rust toolchains, locked dependencies, native Rust tests, and synthetic native storage round trips. It builds the arm64 app and DMG with the approved deployment floor.
3. Artifact inspection: Checks app identity, architecture, signature, payload and resource inventories, DMG contents, source provenance, toolchain and runner details, dependency notices, and SHA-256 checksums. The uploaded Actions artifact is qualification evidence, not a published release, and currently has 14-day retention.

The workflow is manually dispatchable, runs on the qualification branch, and runs for relevant pull requests. It uses read-only repository permissions, pinned action revisions, lockfile-keyed dependency caching, and no signing secrets.

It does not launch the installed GUI on the recipient Mac, publish a release, or establish a reproducible byte-identical DMG build.

Qualification Methodology

Qualification is layered, and each layer answers a different question.

Automated local/Linux checks

Evidence it can establish

• Type correctness, lint, data and distribution invariants, browser workflows, production content gates, and automated accessibility rules exercised by those tests.

What it cannot establish

• Installed macOS behavior, native dialogs, actual assistive technology use, or human comprehensibility.

Hosted macOS arm64 CI

Evidence it can establish

• Native compilation and tests, synthetic storage round trips, architecture and bundle identity, signature and package inspection, checksums, and recorded build provenance.

What it cannot establish

• Launch success and usability on the recipient's machine, physical workload performance, or human accessibility qualification.

Native hardware acceptance

Evidence it can establish

• Behavior of the exact installed artifact on target macOS hardware: trust prompts, launch, persistence, native WebKit, dialogs, restart, resources, and manual interaction.

What it cannot establish

• General release approval until the full defined verification matrix is complete and passes.

Human accessibility verification

Evidence it can establish

• Keyboard and assistive-technology interaction, reading order and announcements, comprehension, and the defined manual checks on target platforms.

What it cannot establish

• Checks outside the completed matrix or platforms not evaluated.