myfiles

myfiles is a local-first, read-only file inventory and backup-confidence tool for explicitly configured SSH-accessible hosts, drives, and roots.

The app may manage its own metadata database, config, cache, labels, annotations, reports, and generated plans. It must never delete, move, rename, rewrite, or otherwise mutate target files.

Project Layout

Cargo.toml                 Rust workspace
backend/                   Axum API/server crate and binary: myfiles-api
crates/myfiles-core/       Shared app constants and read-only guarantees
crates/myfiles-db/         Database layer crate
crates/myfiles-scan/       Scanner/inventory crate
crates/myfiles-cli/        Scriptable CLI binary: myfiles
crates/myfiles-tui/        Terminal UI binary: myfiles-tui
frontend/                  SvelteKit static frontend served by the API in production
docs/unaddressed/notes/    Active implementation backlog
docs/addressed/notes/      Completed backlog notes
drives/                    Real df-style host/filesystem fixtures
mk/                        Helper scripts for lint, test, run, and deployment

The workspace is intentionally split by runtime boundary: reusable domain behavior lives in library crates under crates/, while backend/, crates/myfiles-cli/, and crates/myfiles-tui/ provide the API, CLI, and terminal binaries.

The current implementation is the first workspace slice. Domain features are still being implemented from docs/unaddressed/notes/, starting with project shape, quality gates, explicit config, database schema, scanning, and query/report workflows.

Prerequisites

• Rust 1.93.1 with rustfmt and clippy
• Node.js and npm for the Svelte frontend
• Docker if using the mk/ wrapper scripts

Rust Commands

Run all Rust tests:

cargo test --workspace

Run strict Rust linting:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings

Show the CLI help:

cargo run -p myfiles-cli -- --help

Install the CLI from the workspace root:

cargo install --path .
myfiles --help

Generate shell completions:

cargo run -p myfiles-cli -- completions zsh
cargo run -p myfiles-cli -- completions bash
cargo run -p myfiles-cli -- completions fish
cargo run -p myfiles-cli -- completions nushell

Run the API/server in development:

APP_NAME="myfiles" \
APP_DOMAIN="http://localhost:5173" \
APP_API="http://localhost:8000" \
cargo run -p myfiles-api

The API keeps the template infrastructure endpoints for now:

• /healthz
• /static/config.json
• /api/template

Frontend Commands

Install dependencies:

cd frontend
npm install

Run frontend checks:

cd frontend
npm run check
npm run build
npm run test -- --run

During development, run the frontend and API in separate terminals:

cd frontend
npm run dev

cargo run -p myfiles-api

Vite serves the frontend on http://localhost:5173; the API defaults to http://localhost:8000.

Production-Like Local Run

Build the frontend first:

cd frontend
npm run build

Then run the API, which serves frontend/build/ unless APP_PUBLIC_DIR is set:

cargo run -p myfiles-api

Open http://localhost:8000.

Docker And Wrapper Scripts

The Docker image builds the Svelte frontend and the myfiles-api Rust binary, then serves the static frontend and API from one process.

Run the integrated wrapper test when Docker is available:

./mk/test

Run wrapper linting:

./mk/lint

Runtime Environment

• APP_NAME: display name exposed through runtime config; defaults to myfiles
• APP_DOMAIN: public site origin used for runtime config and CORS
• APP_API: API origin exposed to the frontend
• APP_HOST_IP: optional host IP surfaced in runtime config
• APP_STATIC_DIR: where the API writes config.json
• APP_PUBLIC_DIR: directory of built frontend files served by the API
• PORT: API listen port, defaults to 8000
• DEBUG: enables a permissive development CSP

Backlog Workflow

Active work lives in docs/unaddressed/notes/. Completed work moves to docs/addressed/notes/ with implementation and test notes, following backlog-methodology.md.

Start with docs/unaddressed/notes/000-roadmap-and-routing.md to understand the implementation order.

More Docs

• docs/tutorial.md for an end-to-end user workflow
• DEVEL.md for maintainer onboarding and codebase architecture
• CONVENTIONS.md for code quality expectations
• backlog-methodology.md for backlog maintenance
• docs/api.md for current backend route notes
• docs/TESTING.md for validation commands
• docs/service-worker.md for frontend caching notes
• docs/types.md for JSON payload shapes
• frontend/README.md for frontend-only details