The Open Source Intelligence Platform is a modular investigation workspace for discovering public profiles, inspecting public X metadata, resolving caller information, searching authorized local datasets, and mapping explicit geospatial evidence. 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"]
        Proxy -->|/map/*| Mapping["social_mapping<br/>FastAPI + GeoJSON"]
        Data --> Volume[("dataset_data<br/>persistent volume")]
        Mapping --> Data
        Mapping --> Cache[("geocoder cache<br/>persistent volume")]
    end

    Search --> X["X API"]
    Mapping --> X
    Mapping --> Nominatim["Nominatim<br/>search-origin geocoding"]
    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
• explicit geospatial dataset evidence, radius search, and combined GeoJSON responses
• a durable, rate-limited search-origin geocoder cache
• helper scripts for starting, stopping, rebuilding, and viewing logs
• a unified Electron interface with identity search, native map, dataset import, integration status, and local history workspaces

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. Explore the Map workspace by entering a place, radius, optional keyword, and source selection. Results retain source, accuracy, confidence, timestamps, provenance, and associated identity metadata.
7. Manage integrations by reviewing the configured and reachable state of X/Tweepy, Twilio Lookup, local datasets, and Social Mapping, 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 22 or newer and npm to run the Electron UI
• Optional X API and Twilio credentials for their corresponding live 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
curl http://127.0.0.1/map/readyz

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, Map, Datasets, Integrations, and History workspaces. The native Map workspace calls the shared /map/search API rather than embedding the standalone client. Credential-free dataset mapping remains available when X is not configured. Imported records preserve their dataset, source, observation time, optional confidence, normalized fields, associations, coordinates when explicitly supplied, 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. A map marker is source evidence, not proof of a person's present location. Free-text profile locations are never converted into claimed post coordinates, and associated phone data never creates or implies a phone or device location. 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.