Development Setup

Detailed guide for configuring your local development environment, IDE, debugging tools, and day-to-day workflows.

Hybrid Architecture

ThreatWeaver uses a hybrid local development setup:

Component	Runs In	Port
PostgreSQL	Docker container	5434
Backend (Express + TypeScript)	Host machine (native)	4005
Frontend (React + Vite)	Host machine (native)	3005
Redis	Not used locally	--

Never run the frontend or backend in Docker for local development. The docker-compose.yml is configured so that only PostgreSQL runs in Docker. Redis caching degrades gracefully when unavailable.

IDE Setup

VS Code (Recommended)

Recommended extensions:

• ESLint -- Linting for TypeScript
• Prettier -- Code formatting
• TypeScript Importer -- Auto-import suggestions
• Tailwind CSS IntelliSense -- Class name autocomplete for the frontend
• PostgreSQL -- Database explorer and query runner
• Docker -- Container management
• Mermaid Preview -- Preview Mermaid diagrams in docs

Debugging Configuration

Add to .vscode/launch.json for backend debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Backend",
      "runtimeExecutable": "npx",
      "runtimeArgs": ["tsx", "src/index.ts"],
      "cwd": "${workspaceFolder}/backend",
      "env": { "NODE_OPTIONS": "--max-old-space-size=8192" },
      "console": "integratedTerminal"
    }
  ]
}

Starting the Development Stack

# Terminal 1: PostgreSQL
docker-compose up -d postgres

# Terminal 2: Backend
cd backend && npm run dev

# Terminal 3: Frontend
cd frontend && npm run dev

The backend uses tsx watch with 8GB heap allocation, which provides automatic hot reload on file changes.

The frontend uses Vite with HMR (hot module replacement) for instant UI updates.

Database Access

DB Shell

docker-compose exec -T postgres psql -U tenable -d tenable_dashboard

Common Queries

-- Count all entities
SELECT count(*) FROM pg_tables WHERE schemaname = 'public';

-- Check recent vulnerabilities
SELECT id, plugin_name, severity FROM vulnerabilities ORDER BY created_at DESC LIMIT 10;

-- Check pentest findings
SELECT id, finding_type, severity, confidence FROM pentest_findings ORDER BY created_at DESC LIMIT 10;

-- View active assessments
SELECT id, status, target_url FROM pentest_assessments WHERE status != 'completed';

Migration Commands

npm run migrate:local      # Create/update tables + seed data
npm run migrate:dev        # Cloud DB, multi-tenant aware
npm run migrate:production # Transaction-safe, validated
npm run migrate:status     # Show applied vs pending

Running Tests

# Backend tests (Vitest)
cd backend && npm test

# Frontend tests (Vitest)
cd frontend && npm test

Always run tests after making changes. The test runner watches for file changes in dev mode.

Build Verification

Before pushing any changes, verify the build succeeds locally:

# Backend build check
cd backend && rm -rf dist && npm run build && npm start

# Frontend build check
cd frontend && npm run build

The backend build uses tsc to compile TypeScript to JavaScript in the dist/ directory, then starts with node dist/index.js.

Environment Variables

Copy .env.example to .env in the backend directory. Key variables for local development:

Variable	Local Default	Purpose
PORT	4005	Backend API port
NODE_ENV	development	Environment mode
DB_HOST	localhost	PostgreSQL host
DB_PORT	5434	Docker-mapped PostgreSQL port
DB_USER	admin	Database user
DB_PASSWORD	admin123	Database password
DB_NAME	tenable_dashboard	Database name
JWT_SECRET	(generate)	openssl rand -hex 32
LICENSE_KEY	(from TLM)	JWT license token

Troubleshooting

Issue	Solution
Backend won't start	Check if PostgreSQL is running: docker ps
Port 4005 in use	Kill the existing process: lsof -ti:4005 | xargs kill
Migration fails	Check DB connection, run npm run migrate:status
Frontend blank page	Clear browser cache, check console for errors
Out of memory	Increase Node heap: NODE_OPTIONS='--max-old-space-size=8192'