Skip to content

pcon.md

Latest commit

 

History

History
365 lines (318 loc) · 17.9 KB

pcon.md

File metadata and controls

365 lines (318 loc) · 17.9 KB
Raw

SOCMINT.AI — Full Project Context

Project Overview

Field Value
Name SOCMINT.AI
Description AI-powered Social Media Intelligence & Digital Identity Correlation Platform — an autonomous investigation platform for discovering, correlating, analyzing, and visualizing publicly available digital footprints across social media platforms and OSINT sources.
Type Full-stack web application with AI/ML backend
Status Hackathon prototype (production-ready design patterns)
Repository Root D:\Hackethon\cidecode
Git Yes, initialized

The system enables authorized investigators to enter identifiers (usernames, emails, phones, URLs, images) and autonomously runs a 14-agent AI pipeline to discover accounts, correlate identities across platforms, analyze content/behavior, build relationship graphs, and generate investigation reports.

Tech Stack

Frontend — socmint/

Technology Version/Notes
Next.js 16.2.9 (latest, with breaking changes — see AGENTS.md)
React 19.2.4
TypeScript 5.x
Styling TailwindCSS v4 (@tailwindcss/postcss)
State Management React Context (custom AppStoreProvider)
Charts Nivo (@nivo/* — bar, bump, calendar, heatmap, line, network, pie, radar, sankey, scatterplot, stream, treemap, funnel)
Graph Visualization React Flow (components/graphs/RelationshipGraph.tsx)
Auth Custom JWT-based
Agent Runtime agentation v3.0.2 (loaded in layout)

Backend API — backend/

Technology Version/Notes
Runtime Node.js with ES Modules ("type": "module")
Framework Express 5.1.0
Database MongoDB (Mongoose 9.7.0), Neo4j (driver 6.1.0)
Cache Redis (ioredis 6.0.0)
Auth JWT (jsonwebtoken), Argon2 via crypto, TOTP (otplib)
Real-time Socket.io 4.8.3
Validation Zod 3.24.2
Security Helmet 8.1, CORS, CSRF, CAPTCHA
Testing Jest 30.4

ML/AI Backend — ml-backend/

Technology Version/Notes
Framework FastAPI 0.115.12 (Python 3.x)
NLP NLTK, TextBlob, Transformers, Sentence-Transformers
Vision CLIP (sentence-transformers), face-recognition, imagehash
Audio OpenAI Whisper (openai-whisper)
Similarity RapidFuzz 3.12.2
HTTP httpx 0.28.1
PDF WeasyPrint
Storage boto3 (S3/MinIO)
Infrastructure Uvicorn, PyDantic 2.11

Databases

Database Purpose
MongoDB Users, sessions, cases, reports, audit logs, organizations, evidence, social profiles, content/behavior analysis, intelligence findings
Neo4j Identity relationship graph — accounts, emails, usernames, platforms, connections, communities
Redis Cache, session storage, agent state, job queue
MinIO/S3 Profile images, investigation reports, exported evidence, PDFs

Project Structure

D:\Hackethon\cidecode
├── .agents/                          # Empty (agent configuration placeholder)
├── .git/
├── .vscode/
│
├── socmint/                          # Next.js 16 Frontend
│   ├── app/                          # Next.js App Router pages
│   │   ├── analytics/
│   │   ├── cases/
│   │   ├── dashboard/[role]/         # Dynamic role-based dashboards
│   │   ├── graphs/
│   │   ├── investigations/
│   │   ├── organizations/
│   │   ├── profile/
│   │   ├── reports/
│   │   ├── settings/
│   │   ├── signin/
│   │   ├── users/
│   │   ├── layout.tsx                # Root layout (Agentation, Providers, theme)
│   │   ├── page.tsx                  # Root page → redirects to /signin or /dashboard/[role]
│   │   └── globals.css
│   ├── components/
│   │   ├── graphs/RelationshipGraph.tsx
│   │   ├── layouts/{Providers,BrowserTitleManager,ThemeToggle}.tsx
│   │   └── voice/{VoiceCommandButton,index}.tsx
│   ├── features/roles/               # Role-specific dashboards (8 roles)
│   │   ├── PlatformAdminDashboard.tsx
│   │   ├── OrganizationAdminDashboard.tsx
│   │   ├── CaseSupervisorDashboard.tsx
│   │   ├── InvestigatorDashboard.tsx
│   │   ├── OSINTAnalystDashboard.tsx
│   │   ├── DigitalForensicsDashboard.tsx
│   │   ├── AuditorDashboard.tsx
│   │   └── ViewerDashboard.tsx
│   ├── services/                     # Frontend service layer (18 services)
│   │   ├── apiClient.ts             # Core HTTP client (GET/POST/PUT/PATCH/DELETE)
│   │   └── {analytics,audit,case,evidence,intelligence,...}.service.ts
│   ├── hooks/                        # Custom React hooks
│   │   └── {useCase,useInvestigation,useNotifications,useVoiceDispatcher,...}.ts
│   ├── store/index.tsx               # React Context-based global state
│   ├── types/index.ts                # TypeScript type definitions
│   └── lib/constants.ts              # Navigation items
│
├── backend/                          # Express 5 API Gateway
│   ├── src/
│   │   ├── server.js                 # Entry point — starts HTTP + WS + DB connections
│   │   ├── app.js                    # Express app — middleware + route registrations
│   │   ├── config.js                 # Environment-based configuration
│   │   ├── controllers/              # 16 controllers (auth, cases, user, etc.)
│   │   ├── models/                   # 26 Mongoose models (MongoDB)
│   │   ├── routes/                   # 18 route files
│   │   ├── services/                 # 10 services (auth, neo4j, redis, ml, pipeline, etc.)
│   │   ├── middleware/               # 7 middleware (auth, role, csrf, rate-limit, etc.)
│   │   ├── sockets/                  # Socket.io handlers (auth, notifications, investigation)
│   │   ├── schemas/                  # Mongoose schemas (entities, investigations)
│   │   ├── jobs/                     # Cron jobs (agentMonitor, compliance, index)
│   │   ├── events/                   # Empty (placeholder)
│   │   ├── queues/                   # Empty (placeholder)
│   │   ├── modules/                  # Empty (placeholder)
│   │   ├── utils/                    # 8 utilities (rbac, crypto, auditLogger, etc.)
│   │   └── scripts/                  # Seed scripts (seed-users, createIndexes)
│   ├── __tests__/                    # Jest tests (neo4j, pipeline, visual)
│   ├── storage/                      # File storage directory
│   └── jest.config.mjs
│
├── ml-backend/                       # FastAPI AI/ML Service
│   ├── app/
│   │   ├── main.py                  # FastAPI app — 30+ endpoints, 14-agent pipeline
│   │   ├── orchestrator.py          # Full pipeline orchestrator (14 stages)
│   │   ├── discovery.py             # Username discovery across platforms
│   │   ├── enrichment.py            # Profile metadata enrichment
│   │   ├── correlation.py           # Identity correlation engine
│   │   ├── scoring.py               # Weighted confidence scoring
│   │   ├── content.py               # NLP content analysis
│   │   ├── behavior.py              # Behavioral analysis
│   │   ├── relationship.py          # Relationship graph analysis
│   │   ├── false_positive_guard.py  # Anti-false-positive gating
│   │   ├── ghost_filter.py          # Ghost/false-profile detection
│   │   ├── source_verification.py   # Source reliability scoring
│   │   ├── report.py                # PDF/HTML report generation
│   │   ├── timeline_builder.py      # Cross-platform timeline
│   │   ├── voice.py                 # Whisper voice processing
│   │   ├── anomaly_detection.py     # Activity anomaly detection
│   │   ├── engagement_signals.py    # Engagement metrics
│   │   ├── web_mentions.py          # Web mention search
│   │   ├── email_discovery.py       # Email-based discovery
│   │   ├── phone_discovery.py       # Phone-based discovery
│   │   ├── breach_lookup.py         # Breach data check
│   │   ├── tone_classifier.py       # Tone analysis
│   │   ├── osint_tools.py           # OSINT tool framework
│   │   └── services/
│   │       └── visual_intelligence_service.py  # CLIP + face recognition + imagehash
│   └── tests/                        # 19 pytest test files
│
├── README.md                        # Top-level project README
├── PROJECT_CONTEXT.md               # 1096-line comprehensive project context doc
├── project_context.md               # This file — concise project context summary
├── features.md                      # Detailed feature map & workflows
├── api_documentation.md             # 60+ endpoint API architecture blueprint
├── DATABASE_SCHEMA.md               # 857-line complete MongoDB + Neo4j schema
├── user_hierarchy.md                # 3675-line role hierarchy & access matrix
├── OSINT.md                         # Problem statement and references
├── credentials.txt                  # Seed user credentials for testing
└── pipeline_api_output.json         # Sample pipeline output

Key Files and Their Purposes

Configuration & Setup

File Purpose
backend/src/config.js Central config from env vars (port, DB URIs, JWT secret, etc.)
backend/src/server.js Bootstrap — connects MongoDB/Neo4j/Redis, starts HTTP + WebSocket server
backend/src/app.js Express app — registers all middleware and 17 route groups
socmint/next.config.ts Next.js configuration (currently minimal)
socmint/tsconfig.json TypeScript config (ES2017, bundler resolution, @/* path alias)
socmint/postcss.config.mjs TailwindCSS v4 PostCSS config
ml-backend/app/main.py FastAPI app — all 30+ API endpoints, 14-agent pipeline

Core Backend Services

File Purpose
backend/src/services/pipeline.service.js 683-line investigation pipeline orchestrator — runs 15 agents with parallel groups, persistence, SSE progress
backend/src/services/ml.service.js Lightweight ML backend proxy (fallback)
backend/src/services/neo4j.service.js Neo4j graph database operations
backend/src/services/auth.service.js JWT + Argon2 password auth
backend/src/services/redis.service.js Redis caching + session storage
backend/src/middleware/auth.middleware.js JWT auth gate + role weight hierarchy
backend/src/middleware/role.middleware.js Role-based access control middleware

Frontend Core

File Purpose
socmint/services/apiClient.ts Generic HTTP client with JWT injection, 304 retry, 401 redirect
socmint/store/index.tsx React Context state (user, cases, investigation progress, voice state)
socmint/types/index.ts 18 TypeScript interfaces (Case, IdentityProfile, User, etc.)
socmint/app/layout.tsx Root layout — inline scripts for dynamic title/theme, loads Agentation + Providers

Dependencies

Backend (backend/package.json)

Runtime (13): cookie-parser, cors, dotenv, express (v5), helmet, jsonwebtoken, mongoose, neo4j-driver, node-cron, otplib, qrcode, redis, socket.io, zod

Dev (7): @jest/globals, @types/cors, @types/express, @types/node, jest, nodemon, tsx, typescript

Frontend (socmint/package.json)

Runtime (17): @nivo/bar, bump, calendar, core, funnel, heatmap, line, network, pie, radar, sankey, scatterplot, stream, treemap + next (16.2.9), react (19.2.4), react-dom (19.2.4)

Dev (7): @tailwindcss/postcss, @types/node, @types/react, @types/react-dom, agentation, eslint, eslint-config-next, tailwindcss, typescript

ML Backend (ml-backend/requirements.txt)

Runtime (17): fastapi, pydantic, uvicorn, nltk, textblob, rapidfuzz, httpx, imagehash, face-recognition, openai-whisper, sentence-transformers, phonenumbers, transformers, torch, dnspython, weasyprint, boto3

Build and Run Instructions

Prerequisites

  • Node.js (v20+)
  • Python 3.10+ with venv
  • Access to MongoDB, Neo4j, Redis (cloud instances configured)

Infrastructure Services (Required)

The .env files contain live credentials for:

  • MongoDB Atlas — cloud-hosted MongoDB instance
  • Neo4j Aura — cloud-hosted graph database
  • Redis Cloud — cloud-hosted cache
  • Twitter Bearer Token, GitHub Token, Consumer/Secret Keys for API access

1. ML Backend (Python/FastAPI — port 8000)

cd ml-backend
python -m venv .venv
.venv\Scripts\activate    # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2. Backend API (Node.js/Express — port 4000)

cd backend
npm install
npm run dev               # nodemon src/server.js

3. Frontend (Next.js — port 3000)

cd socmint
npm install
npm run dev               # next dev

Open http://localhost:3000.

Testing Strategies

Backend Tests (backend/__tests__/)

  • Framework: Jest 30 (ESM mode: --experimental-vm-modules)
  • Config: jest.config.mjs — node environment, **/__tests__/**/*.test.js
  • Test files: neo4j.test.js, pipeline.test.js, visual.test.js
  • Commands: 
    npm test                 # Full test run
npm run test:watch       # Watch mode
npm run test:coverage    # With coverage

ML Backend Tests (ml-backend/tests/)

  • Framework: pytest (19 test files)
  • Coverage: correlation, discovery, content, behavior, engagement, enrichment, scoring, source verification, timeline, tone, web mentions, anomaly detection, phone/email discovery, limitations, orchestrator integration, subprocess
  • Command: 
    cd ml-backend
pytest tests/

Frontend

  • No test files found in socmint/
  • ESLint configured (eslint.config.mjs) for linting

Development Conventions

Architecture Patterns

  1. Three-tier: Frontend (Next.js) → API Gateway (Express) → AI Service (FastAPI)
  2. Modular monorepo with three independent services
  3. 14-stage AI pipeline with parallel group execution:
    • Stage 1: discovery, web_mentions (parallel)
    • Stage 2: enrichment, ghost_filter, breach_check
    • Stage 3: content, behavior, visual, relationship (parallel)
    • Stage 4: anomaly_detection, engagement
    • Stage 5: correlation, source_verification
    • Stage 6: report, timeline
  4. RBAC with weighted hierarchy: platform_admin(1000) > org_admin(800) > case_supervisor(500) > investigator(300) > osint_analyst(250) > dfir_analyst(200) > auditor(100) > viewer(50)
  5. SSE streaming for investigation pipeline progress
  6. WebSocket (Socket.io) for real-time notifications and investigation status
  7. Stateless sessions using sessionStorage + JWT on frontend
  8. Context-based state management

Code Organization

  • Backend: MVC-style — routes → controllers → services → models
  • Frontend: Feature-based with role-specific dashboard components
  • ML Backend: Modular per-agent modules with a central orchestrator
  • Naming: camelCase for JS/TS, snake_case for Python, kebab-case for directories

Authentication Flow

  1. User enters credentials + CAPTCHA + behavioral data
  2. Server validates → returns JWT token + user object
  3. Token stored in sessionStorage (socmint_token, socmint_user)
  4. JWT in Authorization: Bearer header or httpOnly cookie
  5. Session rotation, MFA (TOTP), device fingerprinting supported

Seed Users (8 roles)

8 pre-seeded accounts with password Password123:

  • sys.admin — platform_admin
  • org.admin — organization_admin
  • case.sup — case_supervisor
  • niteshinvestigator.investigator — investigator
  • ana.osint — osint_analyst
  • dfir.tech — digital_forensics_analyst
  • auditor.read — auditor
  • viewer.executive — viewer

Observations and Recommendations

Strengths

  1. Comprehensive documentation — 5,800+ lines across docs (PROJECT_CONTEXT, features, API, DB schema, user hierarchy)
  2. Real infrastructure — actual MongoDB Atlas, Neo4j Aura, Redis Cloud connections (not mock/local)
  3. Production-security patterns — Argon2 password hashing, JWT with rotation, MFA, CAPTCHA, behavioral biometrics, CSRF, rate limiting, Helmet
  4. Sophisticated AI pipeline — 14-agent system with parallel execution, false-positive guards, ghost profile filtering, confidence scoring with explainable factors
  5. Complete RBAC system — 8 roles with weighted hierarchy matching law-enforcement chain of command
  6. Multi-modal intelligence — username, email, phone, URL, image, voice, web mentions, breach data
  7. Strong ethical boundaries — no hardcoded fixtures, no fabricated data, public sources only

Potential Issues / Gaps

  1. No frontend tests — zero test files in socmint/
  2. Hardcoded secrets in .env files — committed to repo with real API keys/tokens/database credentials (security risk)
  3. Empty directories — events/, queues/, modules/ are stubs
  4. Zustand mentioned in docs but not used — actual state management uses React Context
  5. NextAuth mentioned but not installed — custom auth implementation instead
  6. ml-backend/.env is identical to backend/.env — suggests a copy-paste without adjusting for ML-specific vars
  7. No Docker/docker-compose — each service must be started manually in separate terminals
  8. No CI/CD configuration — no GitHub Actions, no deployment scripts
  9. credentials.txt committed — contains plaintext passwords
  10. niteshinvestigator.investigator username looks like a typo or placeholder