How Is the IPED Project Structured? A Deep Dive into the Maven Multi-Module Architecture

The IPED project is a Maven multi-module Java application organized into eight distinct layers, from foundational APIs (iped-api) to the desktop UI (iped-app), with strict dependency rules that enforce separation between parsing engines, carving utilities, and user interface components.

The IPED (Indexador e Processador de Evidências Digitais) project is an open-source digital forensics toolkit hosted at sepinf-inc/IPED. Understanding how the IPED project is structured helps developers extend its capabilities with custom parsers or integrate its search capabilities into external tools. The codebase follows a layered architecture defined in the root pom.xml, ensuring that low-level utilities remain independent while higher-level modules orchestrate the processing pipeline.

Maven Multi-Module Layout

The root pom.xml declares eight sub-modules, each packaged as a dedicated JAR with a specific responsibility. This separation allows the forensic engine to run headlessly while the desktop UI depends on the same core libraries.

Module	Package Root	Primary Responsibility
iped-api	iped.api	Core public interfaces for search (IIPEDSearcher), data sources, and configuration.
iped-utils	iped.utils	Generic utilities for logging, compression, and I/O helpers like IOUtil.java.
iped-parsers	iped.parsers	File-type specific parsers (PDF, video, DBF, browser histories). Implementation resides in iped-parsers-impl.
iped-viewers	iped.viewers	UI rendering components for images, PDFs, and maps. Split into iped-viewers-api and iped-viewers-impl.
iped-carvers	iped.carvers	Data carving engines for recovering embedded files. Also split into API and implementation modules.
iped-geo	iped.geo	Geolocation utilities including GPS extraction and map rendering support.
iped-engine	iped.engine	The processing core containing the Manager class that orchestrates case loading, indexing, and hash-database handling.
iped-app	iped.app	The desktop Swing UI entry point (AppMain.java) that boots the application and loads configurations.

Layered Architecture and Dependencies

The IPED project structure enforces a strict unidirectional dependency flow. Lower layers have no knowledge of upper layers, while upper layers explicitly declare dependencies in their respective pom.xml files.

Dependency direction flows upward:

1. Foundation Layer: iped-api and iped-utils provide interfaces and helper classes used by all other modules.
2. Processing Layer: iped-parsers, iped-carvers, and iped-geo implement specific forensic logic and depend only on the foundation.
3. Engine Layer: iped-engine coordinates the parsing pipeline and indexing services, importing the processing modules.
4. Presentation Layer: iped-viewers (API and implementations) renders content and depends on the engine and processing layers.
5. Application Layer: iped-app sits at the top, importing viewers and engine to provide the final desktop interface.

Central configuration is loaded via Configuration.getInstance() within the engine and injected into the UI and viewers at runtime. This design ensures that new parsers or viewers can be added as additional Maven modules without modifying the core engine code.

Core Modules Explained

iped-api: The Public Contract

The iped-api module defines the stable interfaces that external tools use to integrate with IPED. The IIPEDSearcher interface in iped-api/src/main/java/iped/search/IIPEDSearcher.java defines the contract for executing queries, while SearchResult handles result iteration. No implementation details exist in this module, ensuring that dependent projects only need this JAR to compile against IPED.

iped-engine: The Processing Orchestrator

Located at iped-engine/src/main/java/iped/engine/core/Manager.java, the Manager class serves as the central lifecycle coordinator. It handles case loading, starts indexing workers, manages transcription services, and provides access to the searcher instance. When the application performs forensic processing, the Manager delegates tasks to parsers and carvers while maintaining the search index.

iped-parsers and iped-carvers: Extensible Plugins

Both modules follow a service-provider pattern. iped-parsers-impl contains concrete implementations like PDFToThumb.java for PDF thumbnail generation, while iped-carvers-impl includes implementations such as ZIPCarver.java for recovering embedded ZIP archives. Runtime discovery occurs through files in src/main/resources/META-INF/services/, allowing developers to drop new JARs into the classpath to extend functionality.

iped-viewers: Content Rendering

Viewers implement the IViewer interface defined in iped-viewers-api. These components handle the rendering of specific file types within the desktop UI. The separation between API and implementation allows the engine to reference viewer interfaces without importing Swing or JavaFX dependencies directly.

iped-app: The Desktop Entry Point

The AppMain class in iped-app/src/main/java/iped/app/ui/AppMain.java serves as the application bootstrap. It performs JRE version validation, initializes the configuration singleton, and launches the Swing-based user interface, effectively wiring together all lower layers.

Working with the IPED Codebase

Performing a Search via the Public API

The following example demonstrates how to obtain a searcher instance from the engine and execute a query:

import iped.api.search.IIPEDSearcher;
import iped.api.search.SearchResult;
import iped.engine.core.Manager;

// Obtain the configured searcher from the running Manager instance
IIPEDSearcher searcher = Manager.getInstance().getSearcher();

// Execute a query and iterate results
SearchResult result = searcher.search("filetype:pdf AND author:\"John Doe\"");
while (result.hasNext()) {
    var item = result.next();  // iped.data.IItem
    System.out.println(item.getPath());
}

Key classes referenced: IIPEDSearcher (iped-api/src/main/java/iped/search/IIPEDSearcher.java) and SearchResult (iped-api/src/main/java/iped/search/SearchResult.java).

Implementing a Custom Parser

To add support for a new file format, create a class in the iped-parsers-impl module extending AbstractParser:

import iped.parsers.AbstractParser;
import iped.data.IItem;
import java.io.File;

public class MyCustomParser extends AbstractParser {
    @Override
    public boolean isSupported(File file) {
        return file.getName().endsWith(".myfmt");
    }

    @Override
    public void parse(File file, IItem item) throws Exception {
        // Extraction logic
        item.addMetadata("customField", "extractedValue");
    }
}

Register the parser by adding its fully qualified class name to iped-parsers-impl/src/main/resources/META-INF/services/iped.parsers.Parser. The engine automatically discovers and loads the service at runtime.

Launching the UI Programmatically

To start the desktop application from within another Java process:

public class Launcher {
    public static void main(String[] args) {
        // Invoke the same entry point used by the distribution JAR
        iped.app.ui.AppMain.main(new String[] {});
    }
}

The AppMain.main method handles JRE compatibility checks, loads the XML configuration, and initializes the Swing event loop.

Summary

• IPED uses Maven multi-module structure with eight modules ranging from iped-api (interfaces) to iped-app (desktop UI).
• Strict layering prevents circular dependencies: utilities and API form the base, while the application layer sits at the top.
• Extension points are standardized through META-INF/services/ files, enabling drop-in parsers and carvers without engine modification.
• Core orchestration happens in iped-engine/src/main/java/iped/engine/core/Manager.java, which coordinates indexing, parsing, and search services.
• Entry point for the desktop experience is iped-app/src/main/java/iped/app/ui/AppMain.java.

Frequently Asked Questions

What build tool does IPED use?

IPED uses Apache Maven to manage its multi-module structure. The root pom.xml defines the eight sub-modules and shared properties, while each module contains its own pom.xml declaring specific dependencies. Maven enforces the architectural layering by only allowing upper modules to depend on lower ones.

How do I add a new parser to IPED?

Create a new class in iped-parsers-impl that extends AbstractParser or implements the appropriate interface, then register it in src/main/resources/META-INF/services/iped.parsers.Parser. The engine uses Java's ServiceLoader API to discover implementations automatically at runtime, requiring no changes to the core Manager class.

What is the role of the Manager class?

The Manager class (iped-engine/src/main/java/iped/engine/core/Manager.java) acts as the central orchestrator for the forensic processing pipeline. It handles case initialization, starts worker threads for indexing, manages connections to hash databases, and provides the IIPEDSearcher instance used to query processed evidence. It effectively bridges the processing layer and the user interface.

How are the modules organized by dependency direction?

Dependencies flow strictly upward: iped-api and iped-utils have no internal dependencies; iped-parsers, iped-carvers, and iped-geo depend on the API/utilities; iped-engine imports the parsers and carvers; iped-viewers depends on the engine; and iped-app imports all of the above. This ensures that changes in the UI layer cannot break the parsing engine, and the core API remains stable for external integrations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}