Skip to content

Developer Guide

Jump to bottom
LitapAI_Rohit edited this page Jul 8, 2026 · 1 revision

Developer Guide

This guide is intended for developers who want to understand, contribute to, or extend MailIntel AI.

The project follows modern Python development practices with a strong emphasis on maintainability, modularity, automated testing, and reproducible builds.

Development Environment

Requirements

  • Python 3.13+
  • Git
  • Docker Desktop (optional)
  • VS Code (recommended)

Clone Repository

git clone https://github.com/Litap-AI/mailintel-ai.git

cd mailintel-ai

Create Virtual Environment

python -m venv .venv

Activate:

macOS / Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

Install Dependencies

pip install -e ".[dev]"

Run Application

python -m streamlit run src/mailintel/ui/app.py

Repository Structure

mailintel-ai/

├── src/
│   └── mailintel/
│       ├── ai/
│       ├── intelligence/
│       ├── parsers/
│       ├── reporting/
│       ├── scoring/
│       ├── ui/
│       └── workflows/
│
├── tests/
│
├── docs/
│
├── samples/
│
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

Development Workflow

Typical workflow:

Feature Branch

↓

Implementation

↓

Unit Tests

↓

Ruff

↓

MyPy

↓

Pre-commit

↓

GitHub Actions

↓

Merge

Every contribution should pass all quality checks before merging.

Coding Standards

MailIntel AI follows these principles.

Type Hints

All public functions should include explicit type annotations.

Example:

def analyze(email: EmailMessage) -> Investigation:
    ...

Small Modules

Each module should have one primary responsibility.

Avoid combining:

  • Parsing
  • Intelligence
  • Reporting
  • UI

within the same module.

Descriptive Names

Prefer descriptive identifiers.

Good:

investigation_report
risk_score
authentication_result

Avoid:

data
temp
obj
value

Documentation

Every public class and function should include a concise docstring.

Testing

MailIntel AI uses Pytest.

Run all tests:

pytest

Tests are organized by component.

tests/

ai/
intelligence/
parsers/
reporting/
scoring/
workflows/

New features should include corresponding tests.

Static Analysis

Run Ruff:

ruff check .
ruff format . --check

Run MyPy:

mypy src

Run all quality checks:

pre-commit run --all-files

Docker

Build:

docker compose build

Run:

docker compose up

Stop:

docker compose down

Docker ensures a consistent development environment across machines.

Continuous Integration

GitHub Actions automatically performs:

  • Ruff
  • Ruff Format
  • MyPy
  • Pytest

Every pull request is validated before merge.

Adding a New Intelligence Module

To add a new intelligence component:

  1. Create a new module inside src/mailintel/intelligence/.
  2. Implement the analysis logic.
  3. Return structured evidence.
  4. Integrate with the investigation workflow.
  5. Add unit tests.
  6. Update documentation if applicable.

This modular approach keeps new capabilities isolated and easy to maintain.

Release Process

Before creating a release:

  • Run all tests.
  • Verify Docker builds successfully.
  • Review documentation.
  • Update the changelog.
  • Create a Git tag.
  • Publish a GitHub Release.

Each release should represent a stable, reproducible version of the project.

Contributing

Before opening a pull request:

  • Follow the coding standards.
  • Ensure tests pass.
  • Add tests for new functionality.
  • Update documentation if behavior changes.

Contributions that improve quality, maintainability, or documentation are always welcome.

Engineering Philosophy

MailIntel AI is built with the following priorities:

  • Simplicity over unnecessary complexity.
  • Explainability over opaque automation.
  • Modular design over tightly coupled systems.
  • Reproducibility over convenience.
  • Maintainability over rapid but fragile development.

These principles guide architectural and implementation decisions throughout the project.

Clone this wiki locally