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

> Explore the IPED project structure an eight layer Maven multi-module Java application Understand dependency rules separating parsing carving and UI components

- Repository: [Serviço de Perícias em Informática/IPED](https://github.com/sepinf-inc/IPED)
- Tags: deep-dive
- Published: 2026-03-11

---

**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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/PDFToThumb.java) for PDF thumbnail generation, while `iped-carvers-impl` includes implementations such as [`ZIPCarver.java`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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:

```java
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`](https://github.com/sepinf-inc/IPED/blob/main/iped-api/src/main/java/iped/search/IIPEDSearcher.java)) and `SearchResult` ([`iped-api/src/main/java/iped/search/SearchResult.java`](https://github.com/sepinf-inc/IPED/blob/main/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`:

```java
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:

```java
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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/pom.xml) defines the eight sub-modules and shared properties, while each module contains its own [`pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/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`](https://github.com/sepinf-inc/IPED/blob/main/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.