This directory is the single source of truth for the architecture, algorithms, implementation, engineering rationale, and operational guidance of the find tool.
If you are new to the project, read these in order:
- Overview — project goals, scope, non-goals, supported platforms
- Getting Started — install and run a first search (in README)
- Architecture — system design, module responsibilities, data flow
- Algorithms — mathematical foundation, complexity, pseudocode
- CLI — command-line flags and output format
- Configuration — environment variables and runtime constants
- Operations — backup, restore, monitoring, scaling
- Troubleshooting — common issues and resolutions
- FAQ — conceptual questions
| Document | Purpose |
|---|---|
| Overview | Project goals, scope, non-goals, supported platforms, compatibility matrix |
| Architecture | System architecture, module responsibilities, data flow, concurrency model |
| Algorithms | Mathematical derivation, complexity, pseudocode, edge cases |
| Modules | Module-by-module reference for the find crate |
| CLI | Command-line flags, arguments, output format, examples |
| Configuration | Environment variables, constants, run-time behavior |
| Observability | Tracing, logging, audit boundaries, panic handling |
| Performance | Performance characteristics and tuning guide |
| Benchmarks | Criterion suite, how to run, how to interpret results |
| Testing | Testing strategy, test categories, verification methodology |
| Deployment | Docker, systemd, cross-compilation, hardening |
| Operations | Backup, restore, monitoring, scaling, hot upgrades |
| Troubleshooting | Common errors and resolutions |
| Security | Security model, threat model, hardening guidance |
| FAQ | Frequently asked questions (conceptual) |
| Roadmap | Future work, non-goals, supported versions |
| Glossary | Terms, abbreviations, definitions |
| References | External reading and standards |
| Document | Purpose |
|---|---|
| Release Process | Versioning, tagging, building, publishing releases |
| Document | Decision |
|---|---|
| ADR Index | Index of all ADRs |
| ADR-0001 | Multi-variant range-splitting search |
| ADR-0002 | Montgomery simultaneous inversion |
| ADR-0003 | Write-then-rename atomic checkpoints |
| ADR-0004 | Single FindError enum |
| ADR-0005 | Pure search module with CacheWriter trait |
| ADR-0006 | Raw 32-byte X-coordinate binary cache |
- All cross-doc links use relative paths.
- Code blocks include language identifiers (
rust,bash,toml,text). - Diagrams use Mermaid (rendered natively on GitHub).
- File names are lowercase with hyphens (e.g.
getting-started.md). - Top-level files (e.g.
README.md,CHANGELOG.md,LICENSE-MIT) follow the GitHub community convention of being discoverable from the repository root.
See CONTRIBUTING.md and the release process. All substantial changes should be reflected in an ADR — see ADR-0001 for an example of the expected depth.