# Server (Express API Backend)

**Generated:** 2026-02-19
**Location:** server/

## OVERVIEW

Express 5 + TypeScript backend serving REST API endpoints for homelab topology discovery.

## STRUCTURE

```
server/
├── index.ts         # Express app entry, CORS, route mounting
├── config.ts        # Server configuration
├── types.ts         # Shared TypeScript types
├── config.json      # Runtime config (contains hosts, credentials)
├── config.example.json
└── routes/          # API endpoints
    ├── discover.ts  # POST /api/discover - SSH discovery
    ├── config.ts    # GET/PUT /api/config
    ├── stats.ts     # GET /api/stats
    └── files.ts     # GET /api/files
```

## WHERE TO LOOK

| Task | File | Notes |
|------|------|-------|
| Add new endpoint | server/routes/{name}.ts | Create router, import in index.ts |
| Modify CORS | server/index.ts | CORS middleware (line 12-15) |
| Change port | server/index.ts | PORT const (line 9) |

## CONVENTIONS

- **Route files**: Export default router, mount in index.ts via `app.use('/api', router)`
- **Error handling**: Return JSON `{ error: string }` on failure
- **Config**: Use server/config.ts for shared config, not hardcode
- **Credentials**: Never log or expose SSH credentials in responses

## ANTI-PATTERNS

- **NEVER expose SSH credentials in API responses**
- **DO NOT store credentials in source** - use server/config.json

## API ENDPOINTS

| Method | Path | Purpose |
|--------|------|---------|
| POST | /api/discover | Run SSH discovery on hosts |
| GET | /api/config | Get configuration |
| PUT | /api/config | Update configuration |
| GET | /api/stats | Get statistics |
| GET | /api/files | Get file topology |

## NOTES

- Server runs on port 3001
- CORS allows only `http://localhost:3000`
- Health check: GET /api/health