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

```bash
# 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

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

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

### Step 3: Start Frontend

```bash
# 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

```bash
# 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:
   ```javascript
   // You should see:
   { type: 'scan_progress', data: { ... } }
   { type: 'host_discovered', data: { ... } }
   { type: 'scan_complete', data: { ... } }
   ```

## 🐛 Troubleshooting

### Backend Issues

**Port 8000 already in use**
```bash
# Find process
lsof -i :8000
# Kill it
kill -9 <PID>
```

**Permission denied (for nmap)**
```bash
# Run without nmap or with sudo
python main.py
```

**Database locked**
```bash
# Stop all backend instances
pkill -f "python main.py"
# Remove lock
rm scanner.db-journal
```

### Frontend Issues

**Port 3000 already in use**
```bash
# 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:
```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

**Proxy Not Working**

Check `frontend/vite.config.ts`:
```typescript
proxy: {
  '/api': {
    target: 'http://localhost:8000',
    changeOrigin: true,
  },
}
```

## 📝 Development Workflow

### Typical Development Session

```bash
# 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

```bash
# 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

```bash
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`:
```yaml
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:
```bash
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

```bash
# 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](../README.md)
- [QUICKSTART.md](../QUICKSTART.md)
- [ARCHITECTURE.md](../ARCHITECTURE.md)

### Frontend Documentation
- [README.md](./README.md)
- [DEVELOPMENT.md](./DEVELOPMENT.md)
- [FRONTEND_SUMMARY.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! 🔍**