---
title: Madomeda Project Structure
created: '2025-10-23T18:33:48+02:00'
status: draft
priority: 5
published: false
tags: []
reviewers: []
---
# Madomeda Project Structure

## Overview
Madomeda is a Python tool for managing markdown frontmatter in git repositories with rule-based normalization, template-driven generation, and optional LLM assistance.

## Project Structure

```
madomeda/
├── madomeda.py              # Main entry point
├── requirements.txt         # Python dependencies
├── .env                     # LLM configuration
├── README.md               # Project documentation
├── USAGE.md                # Usage examples
│
├── core/                   # Core modules
│   ├── __init__.py
│   ├── database.py         # SQLite database management
│   ├── repository.py       # Git repository operations
│   ├── frontmatter.py      # YAML frontmatter parsing
│   ├── rules.py            # Rule engine
│   ├── template.py         # Template management
│   ├── llm.py             # LLM integration
│   ├── changelog.py        # Changelog management
│   └── processor.py        # Main processing logic
│
├── templates/              # Frontmatter templates
│   └── default.json        # Default template
│
├── rules/                  # Rule definitions
│   ├── tags_normalization.json
│   ├── tag_to_tags.json
│   └── lowercase_keys.json
│
├── prompts/                # LLM prompts
│   └── default.txt         # Default system prompt
│
├── madomeda.db            # SQLite database (gitignored)
└── madomeda_changelog.txt  # Change log

```

## Key Features

### 1. Git Integration
- Tracks markdown files via git ls-files
- Extracts commit history (authors, dates, hashes)
- Ignores hidden files/folders (starting with '.')
- Respects --ignore-paths arguments

### 2. Database Management
- SQLite database (`madomeda.db`)
- Tables: files, frontmatter, commits, tags
- Tracks conformance status
- Stores all frontmatter versions

### 3. Rule Engine
Rules are JSON files in the `rules/` folder:
- **tags_normalization**: Converts tags to lowercase_with_underscores
- **tag_to_tags**: Renames 'tag' key to 'tags'
- **lowercase_keys**: All frontmatter keys must be lowercase

### 4. Template System
Templates define frontmatter structure with value strategies:
- `heur`: Use heuristics (git history, document analysis)
- `orig`: Use original frontmatter value
- `ai <prompt>`: Use LLM with specified prompt

Strategy priority: Options are tried left-to-right until one returns a value.

Example template:
```json
{
  "title": "heur|orig",
  "created": "heur|orig",
  "changed": "heur|orig",
  "authors": "heur|orig",
  "version": "heur|orig",
  "tags": "heur|orig|ai default"
}
```

### 5. LLM Integration
- OpenAI-compatible API support
- Structured output via JSON schema
- Configurable via .env file
- Fallback if API unavailable

### 6. Heuristic Values
- `title`: Extracted from # heading or filename
- `created`: First commit date (ISO 8601)
- `changed`: Latest commit date (ISO 8601)
- `authors`: List of all contributors
- `version`: Latest commit tag if exists, else short hash (7 chars)
- `tags`: Normalized from original

### 7. Changelog
Format:
```
YYYY-MM-DD HH:MM:SS (commit: <hash>)
  path/file.md - frontmatter updated
  ...

```

## Command-Line Arguments

- `--dir PATH`: Repository directory (default: current)
- `--template NAME`: Template to use (default: 'default')
- `--ignore-paths PATH...`: Paths to exclude
- `--whatif`: Dry run mode
- `--no-confirm`: Skip confirmation prompts
- `--force`: Recreate all frontmatter

## Processing Flow

1. **Discovery**: Find tracked .md files via git
2. **Parse**: Extract existing frontmatter
3. **Store**: Save to database with timestamp
4. **Git History**: Extract commit information
5. **Normalize**: Apply rules to frontmatter
6. **Check Conformance**: Compare with template
7. **Build**: Generate new frontmatter from template
8. **Warn**: Alert on metadata loss
9. **Update**: Write to file and database
10. **Log**: Record change in changelog

## Installation

```bash
# Install dependencies
pip install -r requirements.txt

# Configure LLM (optional)
# Edit .env with your OpenAI-compatible API settings

# Run on current directory
python madomeda.py --whatif
```

## Dependencies

- PyYAML: YAML parsing
- python-dotenv: Environment configuration
- openai: LLM integration (optional)

## Notes

- Database and .env are gitignored
- Rules/templates/prompts created automatically on first run
- Empty tag lists are preserved (for template conformance)
- Unicode output replaced with ASCII for Windows compatibility