werkzeuge/teamleader_test/docs/setup/local-development.md

Network Scanner - Full Stack Quick Start Guide

This guide helps you get both backend and frontend running together.

🚀 Quick Start (5 minutes)

Step 1: Start Backend

# From project root
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test

# Start backend server
./start.sh
# OR
python main.py

The backend will be available at: http://localhost:8000

Step 2: Install Frontend Dependencies

# Open new terminal
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test/frontend

# Run setup
./setup.sh
# OR
npm install

Step 3: Start Frontend

# From frontend directory
./start.sh
# OR
npm run dev

The frontend will be available at: http://localhost:3000

Step 4: Use the Application

1. Open browser to http://localhost:3000
2. You'll see the Dashboard
3. Enter a network range (e.g., 192.168.1.0/24)
4. Click "Start Scan"
5. Watch real-time progress
6. Explore the Network Map, Hosts, and Scans pages

📊 Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     USER BROWSER                            │
│                  http://localhost:3000                      │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      │ HTTP/WebSocket
                      │
┌─────────────────────▼───────────────────────────────────────┐
│              VITE DEV SERVER (3000)                         │
│  ┌────────────────────────────────────────────────────┐    │
│  │          React TypeScript Frontend                 │    │
│  │  • Dashboard  • Network Map  • Hosts  • Scans     │    │
│  └────────────────────────────────────────────────────┘    │
│                                                             │
│  Proxy: /api/* → http://localhost:8000/api/*              │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      │ REST API + WebSocket
                      │
┌─────────────────────▼───────────────────────────────────────┐
│           FASTAPI BACKEND (8000)                            │
│  ┌────────────────────────────────────────────────────┐    │
│  │              REST API Endpoints                     │    │
│  │  • /api/scans/*  • /api/hosts/*  • /api/topology/* │    │
│  └────────────────────────────────────────────────────┘    │
│  ┌────────────────────────────────────────────────────┐    │
│  │              WebSocket Endpoint                     │    │
│  │  • /api/ws (real-time updates)                     │    │
│  └────────────────────────────────────────────────────┘    │
│  ┌────────────────────────────────────────────────────┐    │
│  │            Network Scanner Engine                   │    │
│  │  • Port scanning  • Service detection              │    │
│  │  • Topology analysis  • Database storage           │    │
│  └────────────────────────────────────────────────────┘    │
│                                                             │
│  Database: SQLite (scanner.db)                             │
└─────────────────────────────────────────────────────────────┘

🔌 API Integration Details

REST API Flow

Frontend Component
    ↓
Custom Hook (useHosts, useScans, etc.)
    ↓
API Service (services/api.ts)
    ↓
Axios HTTP Request
    ↓
Vite Dev Proxy (/api → :8000/api)
    ↓
FastAPI Backend
    ↓
Database / Scanner
    ↓
JSON Response
    ↓
React State Update
    ↓
UI Re-render

WebSocket Flow

Frontend App Start
    ↓
useWebSocket Hook
    ↓
WebSocket Client (services/websocket.ts)
    ↓
WS Connection: ws://localhost:8000/api/ws
    ↓
Backend WebSocket Manager
    ↓
Scan Events (progress, complete, host_discovered)
    ↓
Message Handler in Hook
    ↓
State Update
    ↓
UI Re-render (real-time)

🧪 Testing the Integration

1. Test Backend Alone

# Check health
curl http://localhost:8000/health

# List hosts
curl http://localhost:8000/api/hosts

# Start scan (from CLI)
python cli.py scan 127.0.0.1

2. Test Frontend-Backend Integration

1. Start both servers
2. Open browser console (F12)
3. Go to Network tab
4. Trigger actions and verify:
   • API calls show in Network tab
   • WebSocket connection established
   • Real-time updates received

3. Test WebSocket

1. Start a scan from frontend
2. Open browser console
3. Watch for WebSocket messages:

   // You should see:
   { type: 'scan_progress', data: { ... } }
   { type: 'host_discovered', data: { ... } }
   { type: 'scan_complete', data: { ... } }
   

🐛 Troubleshooting

Backend Issues

Port 8000 already in use

# Find process
lsof -i :8000
# Kill it
kill -9 <PID>

Permission denied (for nmap)

# Run without nmap or with sudo
python main.py

Database locked

# Stop all backend instances
pkill -f "python main.py"
# Remove lock
rm scanner.db-journal

Frontend Issues

Port 3000 already in use

# Vite will automatically try 3001, 3002, etc.
# Or kill the process:
lsof -i :3000
kill -9 <PID>

Cannot connect to backend

• Verify backend is running: curl http://localhost:8000/health
• Check .env file has correct URLs
• Check browser console for CORS errors

WebSocket not connecting

• Backend CORS must allow WebSocket
• Check WebSocket URL in .env
• Backend must support WebSocket upgrade

Integration Issues

CORS Errors

Backend should have:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Proxy Not Working

Check frontend/vite.config.ts:

proxy: {
  '/api': {
    target: 'http://localhost:8000',
    changeOrigin: true,
  },
}

📝 Development Workflow

Typical Development Session

# Terminal 1: Backend
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test
python main.py

# Terminal 2: Frontend
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test/frontend
npm run dev

# Terminal 3: Testing
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test
python cli.py scan 192.168.1.0/24

Making Changes

Backend Changes

1. Edit Python files
2. Backend auto-reloads (if uvicorn reload enabled)
3. Frontend automatically uses new API

Frontend Changes

1. Edit React/TypeScript files
2. Vite hot-reloads automatically
3. Browser updates instantly

🚢 Production Deployment

Backend

# Option 1: Direct
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Option 2: Gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

# Option 3: Docker
docker build -t network-scanner-backend .
docker run -p 8000:8000 network-scanner-backend

Frontend

cd frontend
npm run build

# Output in: frontend/dist/

Deploy dist/ to:

• Nginx
• Apache
• Netlify
• Vercel
• AWS S3 + CloudFront

Full Stack (Docker Compose)

Create docker-compose.yml:

version: '3.8'
services:
  backend:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data

  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend
    environment:
      - VITE_API_URL=http://localhost:8000
      - VITE_WS_URL=ws://localhost:8000

Run:

docker-compose up -d

🔒 Security Considerations

Development

• Backend and frontend on localhost only
• CORS restricted to localhost:3000
• No authentication (internal use)

Production

Must add:

1. Authentication: JWT, OAuth, or API keys
2. HTTPS: TLS certificates required
3. CORS: Restrict to production domain
4. Rate Limiting: Prevent abuse
5. Input Validation: Already implemented
6. Network Scanning: Ensure authorized networks only

📊 Monitoring

Backend Logs

# Follow logs
tail -f logs/network_scanner.log

# Check for errors
grep ERROR logs/network_scanner.log

Frontend Logs

• Browser console (F12)
• Network tab for API calls
• React DevTools for component inspection

🎯 Common Use Cases

1. Scan Local Network

1. Go to Dashboard
2. Enter: 192.168.1.0/24
3. Select: Quick scan
4. Click: Start Scan
5. Monitor progress
6. View results in Network Map

2. Investigate Specific Host

1. Go to Hosts page
2. Search for IP or hostname
3. Click on host
4. View services and details
5. Check last seen time

3. Monitor Scan Progress

1. Start scan from Dashboard
2. Go to Scans page
3. Watch real-time progress bar
4. View hosts scanned count
5. Cancel if needed

4. Explore Network Topology

1. Complete at least one scan
2. Go to Network Map
3. Pan/zoom to explore
4. Click nodes for details
5. Observe connections

📚 Additional Resources

Backend Documentation

• README.md
• QUICKSTART.md
• ARCHITECTURE.md

Frontend Documentation

• README.md
• DEVELOPMENT.md
• FRONTEND_SUMMARY.md

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

✅ Verification Checklist

After setup, verify:

• Backend running on port 8000
• Frontend running on port 3000
• Can access http://localhost:3000
• Dashboard loads successfully
• Can start a scan
• Real-time updates working
• Network map displays
• Hosts table populated
• WebSocket connected (check console)
• No errors in browser console
• No errors in backend logs

🎉 You're Ready!

Both backend and frontend are now running and integrated. Start scanning your network!

---

Need Help?

• Check browser console for frontend errors
• Check logs/network_scanner.log for backend errors
• Ensure both servers are running
• Verify network connectivity

Happy Scanning! 🔍