# metabarcoding/obitools4 architecture

> Architecture diagram of the GitHub repository metabarcoding/obitools4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metabarcoding/obitools4
- Repository: https://github.com/metabarcoding/obitools4

## Overview

OBITools V4 is a Go toolkit for processing biological sequence and metabarcoding data through command-line tools. The common user workflow is to provide sequence files and options, have a command read and transform or analyze sequence batches, then write results. Distinct capabilities include format conversion, paired-read processing, taxonomy assignment and queries, barcode/PCR handling, k-mer analysis, and summary/statistical work. The graph combines sampled CLI call flows with README and SOURCE INDEX evidence; unsampled tool internals are represented by their exact package directories, without assuming their implementation details.

Main entry points: [`pkg/obitools/obiconvert`](https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obiconvert) (Sequence I/O), [`cmd/obitools/obiannotate/main.go`](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obiannotate/main.go) (Sequence commands), [`cmd/obitools/obitaxonomy/main.go`](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitaxonomy/main.go) (Taxonomy CLI), [`cmd/obitools/obitag/main.go`](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitag/main.go) (Assignment CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command line"]
  node_seq_cli["Sequence commands<br/>[main.go]"]
  node_tax_cli["Taxonomy CLI<br/>[main.go]"]
  node_tag_cli["Assignment CLI<br/>[main.go]"]
  node_pair_cli["Pairing CLI<br/>[main.go]"]
  node_tagpcr_cli["Tag-PCR CLI<br/>[main.go]"]
  node_kmer_cli["K-mer CLI<br/>[main.go]"]
  node_options["Option parsing<br/>[options.go]"]
end

subgraph group_sequence["Sequence processing"]
  node_sequence_data["Sequence model<br/>[biosequence.go]"]
  node_sequence_workers["Sequence workers<br/>[worker.go]"]
  node_batch_workers["Parallel iteration<br/>[workers.go]"]
  node_alignment["Read alignment<br/>[pairedendalign.go]"]
  node_barcode["Barcode matching<br/>[ngslibrary.go]"]
end

subgraph group_taxonomy["Taxonomy"]
  node_taxonomy["Taxonomy model<br/>[taxonomy.go]"]
  node_taxonomy_tools["Taxonomy operations"]
  node_assignment["Taxonomic assignment"]
end

subgraph group_analysis["Analysis tools"]
  node_kmer_tools["K-mer operations"]
  node_kmer_store[("K-mer disk sets<br/>[kmer_set_disk.go]")]
  node_statistics["Statistics<br/>[kmeans.go]"]
  node_pattern["Pattern matching<br/>[apat_search.c]"]
end

subgraph group_formats["Formats and data"]
  node_converter["Sequence I/O"]
  node_formats["Format readers/writers"]
  node_csv_iter["CSV iteration<br/>[csv.go]"]
end

node_user(("User"))

node_user -.->|"runs command"| node_seq_cli
node_seq_cli -->|"parses options"| node_options
node_seq_cli -->|"reads sequences"| node_converter
node_seq_cli -->|"pipes annotations"| node_sequence_workers
node_seq_cli -->|"writes sequences"| node_converter
node_converter -.->|"uses formats"| node_formats
node_user -.->|"runs command"| node_tag_cli
node_tag_cli -->|"reads sequences"| node_converter
node_tag_cli -->|"assigns taxonomy"| node_assignment
node_tag_cli -->|"loads taxonomy"| node_taxonomy
node_tag_cli -->|"writes sequences"| node_converter
node_user -.->|"runs command"| node_tax_cli
node_tax_cli -->|"queries operations"| node_taxonomy_tools
node_tax_cli -->|"reads sequences"| node_converter
node_tax_cli -->|"builds records"| node_csv_iter
node_tax_cli -->|"writes CSV/Newick"| node_formats
node_user -.->|"runs command"| node_pair_cli
node_pair_cli -.->|"assembles reads"| node_alignment
node_pair_cli -->|"writes sequences"| node_converter
node_user -.->|"runs command"| node_tagpcr_cli
node_tagpcr_cli -.->|"pairs reads"| node_alignment
node_tagpcr_cli -->|"writes sequences"| node_converter
node_user -.->|"runs command"| node_kmer_cli
node_kmer_cli -->|"reads sequences"| node_converter
node_kmer_cli -->|"matches k-mers"| node_kmer_tools
node_kmer_cli -->|"writes results"| node_converter
node_batch_workers -->|"applies workers"| node_sequence_workers
node_sequence_workers -->|"transforms sequences"| node_sequence_data
node_barcode -->|"extracts barcodes"| node_sequence_data
node_kmer_store -->|"uses distances"| node_statistics
node_pattern -.->|"searches patterns"| node_pattern

click node_seq_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obiannotate/main.go"
click node_tax_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitaxonomy/main.go"
click node_tag_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitag/main.go"
click node_pair_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obipairing/main.go"
click node_tagpcr_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitagpcr/main.go"
click node_kmer_cli "https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obikmermatch/main.go"
click node_converter "https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obiconvert"
click node_formats "https://github.com/metabarcoding/obitools4/tree/master/pkg/obiformats"
click node_csv_iter "https://github.com/metabarcoding/obitools4/blob/master/pkg/obiitercsv/csv.go"
click node_sequence_data "https://github.com/metabarcoding/obitools4/blob/master/pkg/obiseq/biosequence.go"
click node_sequence_workers "https://github.com/metabarcoding/obitools4/blob/master/pkg/obiseq/worker.go"
click node_batch_workers "https://github.com/metabarcoding/obitools4/blob/master/pkg/obiiter/workers.go"
click node_alignment "https://github.com/metabarcoding/obitools4/blob/master/pkg/obialign/pairedendalign.go"
click node_barcode "https://github.com/metabarcoding/obitools4/blob/master/pkg/obingslibrary/ngslibrary.go"
click node_taxonomy "https://github.com/metabarcoding/obitools4/blob/master/pkg/obitax/taxonomy.go"
click node_taxonomy_tools "https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obitaxonomy"
click node_assignment "https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obitag"
click node_kmer_tools "https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obikmersim"
click node_kmer_store "https://github.com/metabarcoding/obitools4/blob/master/pkg/obikmer/kmer_set_disk.go"
click node_statistics "https://github.com/metabarcoding/obitools4/blob/master/pkg/obistats/kmeans.go"
click node_pattern "https://github.com/metabarcoding/obitools4/blob/master/pkg/obiapat/apat_search.c"
click node_options "https://github.com/metabarcoding/obitools4/blob/master/pkg/obioptions/options.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_seq_cli,node_tax_cli,node_tag_cli,node_pair_cli,node_tagpcr_cli,node_kmer_cli,node_options,node_user toneBlue
class node_sequence_data,node_sequence_workers,node_batch_workers,node_alignment,node_barcode toneAmber
class node_taxonomy,node_taxonomy_tools,node_assignment toneMint
class node_kmer_tools,node_kmer_store,node_statistics,node_pattern toneRose
class node_converter,node_formats,node_csv_iter toneIndigo
```

## Components

### Command line

- [Sequence commands](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obiannotate/main.go): `cmd/obitools/obiannotate/main.go`
- [Taxonomy CLI](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitaxonomy/main.go): `cmd/obitools/obitaxonomy/main.go`
- [Assignment CLI](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitag/main.go): `cmd/obitools/obitag/main.go`
- [Pairing CLI](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obipairing/main.go): `cmd/obitools/obipairing/main.go`
- [Tag-PCR CLI](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obitagpcr/main.go): `cmd/obitools/obitagpcr/main.go`
- [K-mer CLI](https://github.com/metabarcoding/obitools4/blob/master/cmd/obitools/obikmermatch/main.go): `cmd/obitools/obikmermatch/main.go`
- [Option parsing](https://github.com/metabarcoding/obitools4/blob/master/pkg/obioptions/options.go): `pkg/obioptions/options.go`

### Sequence processing

- [Sequence model](https://github.com/metabarcoding/obitools4/blob/master/pkg/obiseq/biosequence.go): `pkg/obiseq/biosequence.go`
- [Sequence workers](https://github.com/metabarcoding/obitools4/blob/master/pkg/obiseq/worker.go): `pkg/obiseq/worker.go`
- [Parallel iteration](https://github.com/metabarcoding/obitools4/blob/master/pkg/obiiter/workers.go): `pkg/obiiter/workers.go`
- [Read alignment](https://github.com/metabarcoding/obitools4/blob/master/pkg/obialign/pairedendalign.go): `pkg/obialign/pairedendalign.go`
- [Barcode matching](https://github.com/metabarcoding/obitools4/blob/master/pkg/obingslibrary/ngslibrary.go): `pkg/obingslibrary/ngslibrary.go`

### Taxonomy

- [Taxonomy model](https://github.com/metabarcoding/obitools4/blob/master/pkg/obitax/taxonomy.go): `pkg/obitax/taxonomy.go`
- [Taxonomy operations](https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obitaxonomy): `pkg/obitools/obitaxonomy`
- [Taxonomic assignment](https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obitag): `pkg/obitools/obitag`

### Analysis tools

- [K-mer operations](https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obikmersim): `pkg/obitools/obikmersim`
- [K-mer disk sets](https://github.com/metabarcoding/obitools4/blob/master/pkg/obikmer/kmer_set_disk.go): `pkg/obikmer/kmer_set_disk.go`
- [Statistics](https://github.com/metabarcoding/obitools4/blob/master/pkg/obistats/kmeans.go): `pkg/obistats/kmeans.go`
- [Pattern matching](https://github.com/metabarcoding/obitools4/blob/master/pkg/obiapat/apat_search.c): `pkg/obiapat/apat_search.c`

### Formats and data

- [Sequence I/O](https://github.com/metabarcoding/obitools4/tree/master/pkg/obitools/obiconvert): `pkg/obitools/obiconvert`
- [Format readers/writers](https://github.com/metabarcoding/obitools4/tree/master/pkg/obiformats): `pkg/obiformats`
- [CSV iteration](https://github.com/metabarcoding/obitools4/blob/master/pkg/obiitercsv/csv.go): `pkg/obiitercsv/csv.go`

### Other components

- **User**

## Connections

- User → Sequence commands: runs command
- Sequence commands → Option parsing: parses options (evidence: `cmd/obitools/obiannotate/main.go`)
- Sequence commands → Sequence I/O: reads sequences (evidence: `cmd/obitools/obiannotate/main.go`)
- Sequence commands → Sequence workers: pipes annotations (evidence: `cmd/obitools/obiannotate/main.go`)
- Sequence commands → Sequence I/O: writes sequences (evidence: `cmd/obitools/obiannotate/main.go`)
- Sequence I/O → Format readers/writers: uses formats
- User → Assignment CLI: runs command
- Assignment CLI → Sequence I/O: reads sequences (evidence: `cmd/obitools/obitag/main.go`)
- Assignment CLI → Taxonomic assignment: assigns taxonomy (evidence: `cmd/obitools/obitag/main.go`)
- Assignment CLI → Taxonomy model: loads taxonomy (evidence: `cmd/obitools/obitag/main.go`)
- Assignment CLI → Sequence I/O: writes sequences (evidence: `cmd/obitools/obitag/main.go`)
- User → Taxonomy CLI: runs command
- Taxonomy CLI → Taxonomy operations: queries operations (evidence: `cmd/obitools/obitaxonomy/main.go`)
- Taxonomy CLI → Sequence I/O: reads sequences (evidence: `cmd/obitools/obitaxonomy/main.go`)
- Taxonomy CLI → CSV iteration: builds records (evidence: `cmd/obitools/obitaxonomy/main.go`)
- Taxonomy CLI → Format readers/writers: writes CSV/Newick (evidence: `cmd/obitools/obitaxonomy/main.go`)
- User → Pairing CLI: runs command
- Pairing CLI → Read alignment: assembles reads (evidence: `cmd/obitools/obipairing/main.go`)
- Pairing CLI → Sequence I/O: writes sequences (evidence: `cmd/obitools/obipairing/main.go`)
- User → Tag-PCR CLI: runs command
- Tag-PCR CLI → Read alignment: pairs reads (evidence: `cmd/obitools/obitagpcr/main.go`)
- Tag-PCR CLI → Sequence I/O: writes sequences (evidence: `cmd/obitools/obitagpcr/main.go`)
- User → K-mer CLI: runs command
- K-mer CLI → Sequence I/O: reads sequences (evidence: `cmd/obitools/obikmermatch/main.go`)
- K-mer CLI → K-mer operations: matches k-mers (evidence: `cmd/obitools/obikmermatch/main.go`)
- K-mer CLI → Sequence I/O: writes results (evidence: `cmd/obitools/obikmermatch/main.go`)
- Parallel iteration → Sequence workers: applies workers (evidence: `pkg/obiiter/workers.go`)
- Sequence workers → Sequence model: transforms sequences (evidence: `pkg/obiseq/worker.go`)
- Barcode matching → Sequence model: extracts barcodes
- K-mer disk sets → Statistics: uses distances (evidence: `pkg/obikmer/kmer_set_disk.go`)
- Pattern matching → Pattern matching: searches patterns (evidence: `pkg/obiapat/apat_search.c`)