# timefs Architecture

This document describes the project shape that the implementation is expected to follow while the filesystem is built out.

## Layers

- `src/cli.rs` parses the `timefs` command line and stays thin.
- `src/config.rs` validates CLI input and turns it into runtime configuration.
- `src/fs/` contains the FUSE-facing implementation and must not talk to the Git library directly.
- `src/git/` contains the Git backend abstraction and implementations.
- `src/cache/` is reserved for inode, object, and directory caches as the filesystem grows.
- `src/errors.rs` holds shared user-facing error types.

## Git Backend Boundary

Filesystem code depends on local traits instead of `gix` directly:

- `RevResolver` resolves revisions to commits.
- `ObjectStore` reads commits, trees, blobs, and symlink targets.

The initial implementation lives in [`src/git/store.rs`](../src/git/store.rs) as `GixRepository`.

## Concurrency Model

The `gix` backend stores a `ThreadSafeRepository` and creates one thread-local `gix::Repository` handle per worker thread.

- No filesystem request path should serialize all repository reads through one global mutex.
- Thread-local handles are created lazily and reused by subsequent operations on the same thread.

## Filesystem Contract

The authoritative Git-to-FUSE mapping is available at
[`docs/FUSE_MAPPING.md`](./FUSE_MAPPING.md), which points at the root
[`FUSE_MAPPING.md`](../FUSE_MAPPING.md) document currently kept in sync with
the implementation work orders.
