Unify live and imported investigations

README.md

@@ -1,26 +1,56 @@
-# whoisit
+# Who Is It?
 
-A lightweight Electron UI for the platform services.
+Who Is It? is the Electron investigation workspace for the OSINT Services Platform.
 
-## What it does
+## Experience
 
-The UI can:
-- probe the platform services over HTTP,
-- attempt to start the Docker Compose stack from the parent platform repository when needed, and
-- call the platform endpoints for username scanning, profile inspection, and phone lookup.
+The application is organized into four work areas:
 
-## Running locally
+- **Search** accepts usernames and phone numbers in one workspace. Auto mode routes clearly formatted phone numbers to phone services and other values to profile services; explicit Profile and Phone modes handle ambiguous identifiers. The source filter can query all sources, only connected live APIs, or only imported datasets. Profile scans retain useful public evidence when paid X inspection has no credits, while phone results combine Twilio metadata with exact E.164 dataset matches.
+- **Datasets** provides one entity ingestion pipeline for CSV, JSON, JSONL, or NDJSON. It previews rows, auto-maps familiar columns, and accepts sparse records containing a username, profile URL, phone number, or any combination of those identifiers.
+- **Integrations** shows whether X/Tweepy, Twilio Lookup, and local datasets are configured and reachable, and provides credential replacement fields.
+- **History** stores the last 50 searches locally and can rerun them. History never leaves the device.
 
-1. Install the dependencies:
-   `npm install`
-2. Start the app:
-   `npm start`
+Provider failures are isolated by source. For example, a Twilio error appears alongside the current phone search while matching imported records remain usable. Selecting **Datasets only** prevents live-provider calls, which is useful when conserving API usage.
 
-The UI calls the running platform services through the nginx proxy on port `80`:
-- `/scan/{username}` for username scanning
-- `/focus?url=...` for profile inspection
-- `/phone_search?phone_number=...` for caller lookup
+## Run and test
 
-## UI screenshot
+Start the parent platform stack first, then:
 
-If you add a screenshot later, place it in the `docs/` directory and name it `ui-screenshot.png`.
+```bash
+npm install
+npm start
+```
+
+Useful commands:
+
+```bash
+npm test          # CSV/JSON/JSONL parser tests
+npm run package   # unpacked desktop application
+npm run make      # distributable artifacts
+```
+
+Development tools are closed by default. Set `WHOISIT_DEVTOOLS=1` before `npm start` when you want Electron DevTools to open automatically.
+
+## Integration credentials
+
+The Integrations workspace can save an X API bearer token, Twilio Account SID, and Twilio Auth Token to the parent platform's ignored `.env` file. Existing values are never returned to the renderer or displayed. Blank fields preserve their current values, writes are atomic, and the resulting file is restricted to the current operating-system user.
+
+After saving, the application attempts to recreate only the affected Compose services. If the desktop process cannot access Docker, the credentials remain saved and the UI asks the user to restart the platform stack manually.
+
+## Data imports
+
+Files are parsed locally in the renderer and sent through nginx to `/datasets/import` as mapped entity rows. Imports are limited to 10 MB and 10,000 records. Every row requires at least one `Username`, `Profile URL`, or E.164 `Phone number`; all other mappings are optional. A row containing both profile and phone fields creates one entity with typed associated identifiers.
+
+Imported results show associated identifiers alongside dataset provenance, source, observation time, confidence, normalized metadata, and the original row. Dataset files may contain sensitive or licensed data; users are responsible for access, retention, and permitted use.
+
+## Service integration
+
+The application talks to `http://127.0.0.1:80`:
+
+- `/scan/{username}`
+- `/focus?url=...`
+- `/phone_search?phone_number=...`
+- `/datasets/...`
+
+The main process checks all four services and can invoke the parent repository's `scripts/start.sh` when the stack is unavailable.

package.json

@@ -2,15 +2,15 @@
   "name": "whoisit",
   "productName": "whoisit",
   "version": "1.0.0",
-  "description": "My Electron application description",
+  "description": "A unified investigation workspace for public profile, phone, and imported dataset searches.",
   "main": ".webpack/main",
   "scripts": {
     "start": "electron-forge start",
     "package": "electron-forge package",
     "make": "electron-forge make",
     "publish": "electron-forge publish",
     "lint": "echo \"No linting configured\"",
-    "test": "echo \"No tests configured\""
+    "test": "node --test tests/*.test.cjs"
   },
   "devDependencies": {
     "@babel/core": "^7.26.0",