biopus/barcode-kit

1. barcode-kit is a local-first DNA barcode pipeline centered on one persistent workspace under data_dir. The core loop is: query GenBank, cache raw records, normalize taxonomy, parse marker sequences, then export FASTA datasets and JSON reports from local state.

2. The main user boundary is the Typer CLI in src/barcode_kit/cli.py. It exposes distinct operational commands for sync, build, qc, and db management, so the repository is organized around command-driven workflows rather than a long-running service.

3. Configuration is loaded from config.py and is part of the architecture, not just convenience. It controls filesystem layout, collector behavior, GenBank credentials, and QC parameters. The default workspace includes a SQLite database plus cache/genbank/ and logs/, which makes local state an explicit subsystem.

4. The ingestion path is genbank.py plus blast.py/itsxrust.py/parser.py around record acquisition and sequence interpretation. sync contacts NCBI E-utilities, fetches accession records, and stores the downloaded GenBank text locally. The README indicates this step can use taxon names or NCBI TaxId, and it supports the markers its, its2, matk, and rbcl.

5. Taxonomy is a separate normalization boundary in taxonomy.py. It uses ETE’s NCBITaxa local taxonomy database to turn NCBI taxon hints or scientific names into canonical names and lineages. This is important because the system treats taxonomy resolution as a local enrichment step before data is written to storage.

6. storage.py is the persistence layer and the main integration point between modules. It maintains the SQLite schema for accession-level cache records and taxonomy rows, and it is also the source of truth for later build and cleanup operations. The db commands operate directly on this layer for status, info, remove, clear, and prune.

7. builder.py implements the dataset construction boundary. It reads only from local cache and produces marker-specific FASTA outputs plus dataset.json and build_report.json. The build stage is intentionally separate from synchronization: it does not re-query NCBI and does not apply QC filters unless the later qc command is run.

8. validation.py is the QC layer that consumes a built dataset and emits a filtered FASTA plus qc_report.json. It supports sequence-level rules like length and ambiguity thresholds, as well as taxonomy-based exclusions. This stage is designed to be repeatable from raw/, not incremental over prior QC outputs.

9. The phylogeny subsystem in phylogeny.py is a thin wrapper around external bioinformatics tools. It orchestrates alignment, trimming, tree building, and TreeShrink-based outlier detection through subprocess runners. The README shows dependencies on mafft, iqtree, trimal, and run_treeshrink.py, so this module is an execution boundary to system-installed tools rather than an in-process algorithm library.

10. The domain layer in models.py, exceptions.py, and __init__.py provides shared objects and error semantics used across the pipeline. That keeps the CLI, storage, parser, and QC code aligned on the same record and report shapes, which is important for generating consistent JSON outputs.

11. The repository also has a clear testing boundary. The tests/ suite covers CLI behavior, GenBank download logic, parser validation, taxonomy, storage, phylogeny, and module exports, which mirrors the architecture of the package and suggests the intended contracts between modules are stable and explicitly verified.