# Core Code API

Central API service providing infrastructure management, home automation, and utility endpoints for the homelab ecosystem.

## Features

### Infrastructure Management
- **Portainer Integration**: Stack and container management
- **NPM Integration**: Nginx Proxy Manager domain and certificate management
- **Service Control**: Start/stop services with container orchestration

### Home Automation (Housekeeping API)
- **Device Control**: Turn on/off, toggle, and set brightness for smart devices
- **Scene Activation**: Trigger Home Assistant scenes
- **Script Execution**: Run Home Assistant scripts
- **Automation Management**: Enable/disable automations
- **State History**: Query device state changes over time
- **Area Discovery**: List rooms and areas

### Utilities
- **DNS Lookup**: Query DNS records (A, AAAA, MX, TXT, CNAME, NS, SOA, PTR)
- **Health Checks**: Service health monitoring with database connectivity status

## Architecture

```
src/
├── config.py                      # Global application settings
├── logging_config.py              # Logging configuration
├── base_controller.py             # Base controller pattern
├── main.py                        # FastAPI application entry point
├── auth/
│   └── oidc.py                    # OIDC authentication
├── clients/
│   ├── homeassistant_client.py    # Home Assistant REST client
│   ├── npm_client.py              # Nginx Proxy Manager client
│   └── portainer_client.py        # Portainer API client
├── controllers/
│   ├── health_controller.py       # Health endpoints
│   ├── housekeeping_controller.py # Home automation endpoints
│   ├── infrastructure_controller.py # Infrastructure management
│   ├── static_controller.py       # Static file serving
│   └── tools_controller.py        # DNS and utility tools
└── dns/
    ├── service.py                 # DNS lookup service
    └── exceptions.py              # DNS-specific exceptions
```

## API Endpoints

### Health
- `GET /` - Service info and documentation links
- `GET /health` - Basic health status
- `GET /health/full` - Detailed component health
- `GET /health/diagnostics` - Full diagnostic information

### Infrastructure (`/infrastructure`)
- `GET /infrastructure/health` - Portainer/NPM connection status
- `GET /infrastructure/services` - List all services (stacks)
- `GET /infrastructure/services/{name}` - Get service details
- `GET /infrastructure/services/{name}/status` - Service status
- `POST /infrastructure/services/{name}/start` - Start service
- `POST /infrastructure/services/{name}/stop` - Stop service
- `GET /infrastructure/containers` - List containers
- `GET /infrastructure/containers/{name}` - Container details
- `GET /infrastructure/containers/{name}/logs` - Container logs
- `GET /infrastructure/ports` - List exposed ports
- `GET /infrastructure/domains` - List proxy domains
- `GET /infrastructure/widget-data` - Dashboard widget data

### Housekeeping (`/housekeeping`)
- `GET /housekeeping/health` - Home Assistant connection status
- `GET /housekeeping/devices` - List controllable devices
- `GET /housekeeping/devices/{entity_id}` - Device details
- `POST /housekeeping/devices/{entity_id}/control` - Control device
- `GET /housekeeping/scenes` - List scenes
- `POST /housekeeping/scenes/{scene_id}/activate` - Activate scene
- `GET /housekeeping/scripts` - List scripts
- `POST /housekeeping/scripts/{script_id}/run` - Run script
- `GET /housekeeping/automations` - List automations
- `POST /housekeeping/automations/{automation_id}/toggle` - Toggle automation
- `GET /housekeeping/history` - State history
- `GET /housekeeping/areas` - List areas/rooms

### Tools (`/tools`)
- `POST /tools/dns/lookup` - DNS record lookup

## Development

### Requirements
- Python 3.12+
- Docker (for containerized deployment)

### Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run locally
uvicorn src.main:app --reload --host 0.0.0.0 --port 8083
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test file
pytest tests/test_housekeeping.py -v
```

### Adding New Dependencies

Dependencies use major version pinning (`~=`) for automatic patch updates while preventing breaking changes.

1. Add package to `requirements.txt` with major version constraint:
   ```
   package-name~=1.2.0  # Allows 1.2.x, blocks 1.3.0
   ```

2. Restart the container to install:
   ```bash
   docker restart core-api
   ```

### Docker Build

```bash
# Build image
docker build -t core-code:latest .

# Run container
docker run -p 8083:8083 core-code:latest
```

## Deployment

### Portainer Stack

1. Navigate to Portainer UI
2. Go to **Stacks** → **Add Stack**
3. Name: `core-code`
4. Upload `stacks/core-code.yml` or paste contents
5. Deploy

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORTAINER_URL` | Portainer API URL | `http://localhost:9000` |
| `PORTAINER_API_KEY` | Portainer API key | - |
| `NPM_URL` | Nginx Proxy Manager URL | `http://localhost:81` |
| `NPM_EMAIL` | NPM admin email | - |
| `NPM_PASSWORD` | NPM admin password | - |
| `HOMEASSISTANT_URL` | Home Assistant URL | `http://localhost:8123` |
| `HOMEASSISTANT_TOKEN` | HA long-lived access token | - |
| `OIDC_ENABLED` | Enable OIDC auth | `false` |
| `OIDC_ISSUER` | OIDC issuer URL | - |
| `OIDC_AUDIENCE` | OIDC audience | - |

## API Documentation

Once deployed, access documentation at:
- **Swagger UI**: http://localhost:8083/docs
- **ReDoc**: http://localhost:8083/redoc
- **OpenAPI Spec**: http://localhost:8083/openapi.json

## Health Checks

- **Basic**: `GET /health` - Fast liveness check for container orchestration
- **Full**: `GET /health/full` - Returns database status (503 if unhealthy)
- **Diagnostics**: `GET /health/diagnostics` - Service info and configuration

## Security

- Runs as non-root user (uid 1000)
- OIDC authentication support via Authentik
- CORS configured for same-network access
- Admin endpoints require authentication when OIDC enabled

## License

Internal use only.