The Open Source Intelligence Platform is a modular investigation workspace for discovering public profiles, inspecting public X metadata, resolving caller information, and searching authorized local datasets. The platform repository brings live and imported sources together behind one nginx endpoint and the whoisit Electron UI.

flowchart LR
    UI["whoisit<br/>Electron + React"] -->|HTTP| Proxy["nginx proxy<br/>localhost:80"]

    subgraph Platform["platform · Docker Compose"]
        Proxy -->|/scan/*| Checker["profile_checker<br/>FastAPI"]
        Proxy -->|/focus*| Search["profile_search<br/>FastAPI + X API"]
        Proxy -->|/phone_search*| Phone["phone_search<br/>FastAPI + Twilio Lookup v2"]
        Proxy -->|/datasets*| Data["dataset_service<br/>FastAPI + SQLite"]
        Data --> Volume[("dataset_data<br/>persistent volume")]
    end

    Search --> X["X API"]
    Phone --> Twilio["Twilio Lookup API"]

The services remain independently runnable, while the platform repository provides:

• Docker Compose orchestration and a shared bridge network
• nginx routing through port 80
• environment-variable injection for external APIs
• health and readiness endpoints
• persistent normalized profile and phone datasets
• helper scripts for starting, stopping, rebuilding, and viewing logs
• a unified Electron search interface with identifier and source filters, type-specific results, and local history

1. Enter a username or phone number in the shared Search workspace. Auto mode routes clearly formatted phone numbers to phone services and other values to profile services; explicit modes handle ambiguous identifiers.
2. Choose sources across all connected services, live APIs only, or imported datasets only. Excluded providers are not called.
3. Inspect a profile to retrieve public X identity fields, media, verification state, dates, pinned/recent post IDs, entities, and metrics. Public scan evidence remains available when paid X inspection is unavailable.
4. Review phone results from Twilio Lookup v2 and exact normalized matches in imported phone datasets.
5. Import authorized data from CSV, JSON, JSONL, or NDJSON through one sparse entity pipeline. Each row can contain a profile identifier, a phone identifier, or both; matching either identifier returns the stored association.
6. Manage integrations by reviewing the configured and reachable state of X/Tweepy, Twilio Lookup, and local datasets, or replacing provider credentials from the desktop UI.

Live providers and imported sources are queried independently. A provider error is shown with that source while successful results from other sources remain available.

All routes are exposed through nginx at http://127.0.0.1:80.

Copy the example file before starting the stack:

cp .env.example .env

Set these values in .env:

Never place real credentials in .env.example, source files, logs, issues, or commits. The local .env file is intentionally ignored by Git. The desktop Integrations workspace never displays existing values; replacements are handled by the Electron main process, written atomically with owner-only permissions, and applied by recreating only the affected API services when Docker is accessible.

• Git, including configured access to the service submodules
• Docker Engine
• Docker Compose through the docker compose command
• Node.js and npm to run the Electron UI
• X API and Twilio credentials for their corresponding features

git clone https://github.com/osint-services/platform.git
cd platform
git submodule update --init --recursive
cp .env.example .env
# Add your credentials to .env
docker compose up --build -d

Or use the provided helper:

./scripts/start.sh

Verify the routed services:

curl http://127.0.0.1/scan/healthz
curl http://127.0.0.1/focus/readyz
curl http://127.0.0.1/phone_search/healthz
curl http://127.0.0.1/datasets/healthz

With the platform stack running:

cd whoisit
npm install
npm start

The UI checks platform availability, can attempt to start the parent Compose stack, and provides Search, Datasets, Integrations, and History workspaces. Search includes Auto, Profile, and Phone modes plus source filters that control which providers are queried. Datasets use one mapping workflow, require only one searchable identifier per row, and retain typed profile and phone metadata under a shared entity. Imported records preserve their dataset, source, observation time, optional confidence, normalized fields, associations, and original row for audit.

From the platform repository:

./scripts/start.sh    # Build and start the stack
./scripts/stop.sh     # Stop the stack
./scripts/build.sh    # Rebuild service images
./scripts/logs.sh     # Stream service logs

Use the platform only for lawful access to public or properly authorized data. Import only data you are permitted to retain and search. Protect API credentials and dataset volumes, respect provider and dataset license terms, apply appropriate retention controls, and consider the privacy and safety impact of collecting or sharing identifying information. The local API currently has no authentication layer and should not be exposed to an untrusted network without access controls.