# laserattack/mado2 architecture

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

- Interactive diagram: https://gitdiagram.com/laserattack/mado2
- Repository: https://github.com/laserattack/mado2

## Overview

Mado is a command-line markdown organizer whose entries live in a local MADO/ directory. The visible workflow dispatches a command, parses an optional query, asks the repository to find or remove matching entries, then formats results; init and new provide repository and entry creation. The query language and entry model are distinct domain stages, with common text/time utilities as an internal layer. The README gives no feature inventory, and some source is unsampled, so uncertain internal links are omitted or marked unverified.

Main entry points: [`code/libmado/src/repository/repository.cpp`](https://github.com/laserattack/mado2/blob/master/code/libmado/src/repository/repository.cpp) (Repository), [`code/cli/command.cpp`](https://github.com/laserattack/mado2/blob/master/code/cli/command.cpp) (Commands), [`code/libmado/src/query/parser.cpp`](https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/parser.cpp) (Query Parser), [`code/cli/main.cpp`](https://github.com/laserattack/mado2/blob/master/code/cli/main.cpp) (CLI Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main["CLI Entry<br/>[main.cpp]"]
  node_commands["Commands<br/>[command.cpp]"]
  node_flags["Flag Parser<br/>[flag.h]"]
  node_flag_context["Flag Context<br/>[flag_context.hpp]"]
  node_formatters["Output Formatters"]
end

subgraph group_query["Query Language"]
  node_lexer["Query Lexer<br/>[lexer.cpp]"]
  node_parser["Query Parser<br/>[parser.cpp]"]
  node_ast["Query AST<br/>[ast.cpp]"]
  node_utf8proc["Unicode Processing<br/>[utf8proc.c]"]
  node_interpreter["Query Interpreter<br/>[interpreter.cpp]"]
end

subgraph group_domain["Entries And Storage"]
  node_repository["Repository<br/>[repository.cpp]"]
  node_entry["Entry Model<br/>[entry.cpp]"]
end

subgraph group_common["Common Utilities"]
  node_text_utils["Text Utilities<br/>[text_utils.cpp]"]
  node_time_utils["Time Utilities<br/>[time_utils.cpp]"]
  node_fuzzy_match["Fuzzy Matching<br/>[fuzzy_match.cpp]"]
end

node_user(("User"))
node_filesystem[("Local Filesystem")]

node_user -->|"runs"| node_main
node_main -->|"parses flags"| node_flag_context
node_flag_context -->|"wraps"| node_flags
node_main -->|"dispatches"| node_commands
node_commands -->|"tokenizes query"| node_lexer
node_commands -->|"parses query"| node_parser
node_commands -->|"runs operations"| node_repository
node_commands -->|"formats results"| node_formatters
node_parser -->|"uses Unicode"| node_utf8proc
node_repository -->|"evaluates filters"| node_interpreter
node_repository -->|"uses text helpers"| node_text_utils
node_repository -->|"uses time helpers"| node_time_utils
node_repository -->|"loads entries"| node_entry
node_repository -->|"reads and writes"| node_filesystem
node_lexer -.->|"supplies tokens"| node_parser
node_parser -.->|"builds tree"| node_ast
node_interpreter -.->|"evaluates tree"| node_ast

click node_main "https://github.com/laserattack/mado2/blob/master/code/cli/main.cpp"
click node_commands "https://github.com/laserattack/mado2/blob/master/code/cli/command.cpp"
click node_flags "https://github.com/laserattack/mado2/blob/master/code/cli/3rdparty/flag.h/flag.h"
click node_flag_context "https://github.com/laserattack/mado2/blob/master/code/cli/flag_context.hpp"
click node_formatters "https://github.com/laserattack/mado2/blob/master/code/cli/entry_info_format.cpp"
click node_lexer "https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/lexer.cpp"
click node_parser "https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/parser.cpp"
click node_ast "https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/ast.cpp"
click node_utf8proc "https://github.com/laserattack/mado2/blob/master/code/libmado/3rdparty/utf8proc/utf8proc.c"
click node_interpreter "https://github.com/laserattack/mado2/blob/master/code/libmado/src/interpreter/interpreter.cpp"
click node_repository "https://github.com/laserattack/mado2/blob/master/code/libmado/src/repository/repository.cpp"
click node_entry "https://github.com/laserattack/mado2/blob/master/code/libmado/src/entry/entry.cpp"
click node_text_utils "https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/text_utils.cpp"
click node_time_utils "https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/time_utils.cpp"
click node_fuzzy_match "https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/fuzzy_match.cpp"

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_main,node_commands,node_flags,node_flag_context,node_formatters,node_user toneBlue
class node_lexer,node_parser,node_ast,node_utf8proc,node_interpreter,node_filesystem toneAmber
class node_repository,node_entry toneMint
class node_text_utils,node_time_utils,node_fuzzy_match toneRose
```

## Components

### CLI

- [CLI Entry](https://github.com/laserattack/mado2/blob/master/code/cli/main.cpp): `code/cli/main.cpp`
- [Commands](https://github.com/laserattack/mado2/blob/master/code/cli/command.cpp): `code/cli/command.cpp`
- [Flag Parser](https://github.com/laserattack/mado2/blob/master/code/cli/3rdparty/flag.h/flag.h): `code/cli/3rdparty/flag.h/flag.h`
- [Flag Context](https://github.com/laserattack/mado2/blob/master/code/cli/flag_context.hpp): `code/cli/flag_context.hpp`
- [Output Formatters](https://github.com/laserattack/mado2/blob/master/code/cli/entry_info_format.cpp): `code/cli/entry_info_format.cpp`

### Query Language

- [Query Lexer](https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/lexer.cpp): `code/libmado/src/query/lexer.cpp`
- [Query Parser](https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/parser.cpp): `code/libmado/src/query/parser.cpp`
- [Query AST](https://github.com/laserattack/mado2/blob/master/code/libmado/src/query/ast.cpp): `code/libmado/src/query/ast.cpp`
- [Unicode Processing](https://github.com/laserattack/mado2/blob/master/code/libmado/3rdparty/utf8proc/utf8proc.c): `code/libmado/3rdparty/utf8proc/utf8proc.c`
- [Query Interpreter](https://github.com/laserattack/mado2/blob/master/code/libmado/src/interpreter/interpreter.cpp): `code/libmado/src/interpreter/interpreter.cpp`

### Entries And Storage

- [Repository](https://github.com/laserattack/mado2/blob/master/code/libmado/src/repository/repository.cpp): `code/libmado/src/repository/repository.cpp`
- [Entry Model](https://github.com/laserattack/mado2/blob/master/code/libmado/src/entry/entry.cpp): `code/libmado/src/entry/entry.cpp`

### Common Utilities

- [Text Utilities](https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/text_utils.cpp): `code/libmado/src/common/text_utils.cpp`
- [Time Utilities](https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/time_utils.cpp): `code/libmado/src/common/time_utils.cpp`
- [Fuzzy Matching](https://github.com/laserattack/mado2/blob/master/code/libmado/src/common/fuzzy_match.cpp): `code/libmado/src/common/fuzzy_match.cpp`

### Other components

- **User**
- **Local Filesystem**

## Connections

- User → CLI Entry: runs (evidence: `code/cli/main.cpp`)
- CLI Entry → Flag Context: parses flags (evidence: `code/cli/main.cpp`)
- Flag Context → Flag Parser: wraps (evidence: `code/cli/flag_context.hpp`)
- CLI Entry → Commands: dispatches (evidence: `code/cli/main.cpp`)
- Commands → Query Lexer: tokenizes query (evidence: `code/cli/command.cpp`)
- Commands → Query Parser: parses query (evidence: `code/cli/command.cpp`)
- Commands → Repository: runs operations (evidence: `code/cli/command.cpp`)
- Commands → Output Formatters: formats results (evidence: `code/cli/command.cpp`)
- Query Parser → Unicode Processing: uses Unicode (evidence: `code/libmado/src/query/parser.cpp`)
- Repository → Query Interpreter: evaluates filters (evidence: `code/libmado/src/repository/repository.cpp`)
- Repository → Text Utilities: uses text helpers (evidence: `code/libmado/src/repository/repository.cpp`)
- Repository → Time Utilities: uses time helpers (evidence: `code/libmado/src/repository/repository.cpp`)
- Repository → Entry Model: loads entries (evidence: `code/libmado/src/repository/repository.cpp`)
- Repository → Local Filesystem: reads and writes (evidence: `code/libmado/src/repository/repository.cpp`)
- Query Lexer → Query Parser: supplies tokens
- Query Parser → Query AST: builds tree
- Query Interpreter → Query AST: evaluates tree
