Indexly Developer Guide

A complete guide for developers to explore Indexly’s architecture, modules, and build process. Learn how to extend search features, add filetype support, and contribute effectively.
Categories:
Tags:

For tinkerers, builders, and curious minds.

Project Structure 

indexly/
│   LICENSE.txt
│   README.md
│   pyproject.toml
└───src/
    └───indexly/
        │   __init__.py
        │   __main__.py
        │   indexly.py
        │   ... (other modules)
        ├───assets/
        │       DejaVuSans-Bold.ttf
        │       DejaVuSans-Oblique.ttf
        │       DejaVuSans.ttf
        └───docs/
                README.md  (canonical documentation)
        └───csv/
                sample.csv

Core Modules

File Purpose
indexly.py Main CLI
cli_utils.py CLI argument setup
output_utils.py Markdown/PDF/JSON exports
fts_core.py Full-text search logic
db_utils.py Database creation/updates
watcher.py Real-time indexing
export_utils.py PDF/TXT/JSON export
path_utils.py Path sanitization
filetype_utils.py Detects/parses file types
log_utils.py Logging & colors

Dev Setup

First, clone the repository and set up a virtual environment:

git clone https://github.com/kimsgent/project-indexly.git
cd project-indexly

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate   # On Linux/Mac
venv\Scripts\activate      # On Windows

# Install requirements
pip install indexly
pip install -r requirements.txt

# If developing, install additional dev requirements
pip install -r requirements-dev.txt

Quick test run:

indexly search "demo"

graph TD
  A[Clone repository] --> B[Install tools: Python, Hatch, Hatchling]
  B --> C[Build & install locally: hatch build / hatch install]
  C --> D[Explore project structure]
  D --> E[Run CLI: indexly --help]
  E --> F[Contribute: edit, test, docs]

  D --> G[indexly/]
  G --> H[src/indexly/]
  H --> I[indexly.py]
  H --> J[__main__.py]
  H --> K[assets/]
  H --> L[docs/]
  H --> M[csv/]
  G --> N[pyproject.toml]
  G --> O[README.md]
  G --> P[LICENSE.txt]

Using Hatch & Hatchling

Indexly also supports Hatch for builds and dependency management. The project includes a pyproject.toml with general and development requirements.

pip install hatch
pip install hatchling
hatch --version

Build and install locally:

hatch build
hatch install

Tips for Extension

  • New filetypes → filetype_utils.py
  • New export formats → output_utils.py
  • CLI options → cli_utils.py
  • New search filters → fts_core.py

References & Next Steps

for advanced search capabilities.

  • Start experimenting with indexing your own documents and images.