syntaxis/core/crates/api/README.md

# Lifecycle API Server

REST API for syntaxis management with explicit configuration file support.

## Configuration

The API server is **completely configuration-driven** and requires an explicit configuration file path via the `--config` argument.

### Running the Server

```bash
# Required: pass configuration file path
./syntaxis-api --config /path/to/config.toml
```

### Configuration File Format

Create a TOML configuration file:

```toml
[server]
host = "127.0.0.1"           # Server host (required)
port = 3000                  # Server port (required)
database_path = "/tmp/data.db"  # Database file path (required, can be absolute or relative)
cors_enabled = true          # Enable CORS (required)
log_level = "info"           # Log level: trace/debug/info/warn/error (required)
```

### Environment Variable Overrides

Environment variables override TOML configuration:

```bash
# Override specific settings
LIFECYCLE_API_HOST=0.0.0.0 LIFECYCLE_API_PORT=8080 ./syntaxis-api --config /path/to/config.toml

# Change log level
LIFECYCLE_API_LOG_LEVEL=debug ./syntaxis-api --config /path/to/config.toml

# Use custom database path
LIFECYCLE_API_DATABASE_PATH=/var/lib/lifecycle/data.db ./syntaxis-api --config /path/to/config.toml

# Disable CORS
LIFECYCLE_API_CORS_ENABLED=false ./syntaxis-api --config /path/to/config.toml
```

## Configuration Examples

### Development Configuration

Create `~/.config/syntaxis-api/dev.toml`:

```toml
[server]
host = "127.0.0.1"
port = 3000
database_path = "/tmp/syntaxis-dev.db"
cors_enabled = true
log_level = "debug"
```

Run:
```bash
./syntaxis-api --config ~/.config/syntaxis-api/dev.toml
```

### Production Configuration

Create `/etc/syntaxis-api/prod.toml`:

```toml
[server]
host = "0.0.0.0"
port = 8080
database_path = "/var/lib/lifecycle/data.db"
cors_enabled = true
log_level = "info"
```

Run:
```bash
./syntaxis-api --config /etc/syntaxis-api/prod.toml
```

### Docker Configuration

Create `./config/docker.toml`:

```toml
[server]
host = "0.0.0.0"
port = 3000
database_path = "/data/project.db"
cors_enabled = true
log_level = "info"
```

Dockerfile:
```dockerfile
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build -p syntaxis-api --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y sqlite3
COPY --from=builder /app/target/release/syntaxis-api /usr/local/bin/
WORKDIR /app
VOLUME ["/data"]
EXPOSE 3000
ENTRYPOINT ["syntaxis-api", "--config", "/etc/syntaxis-api/config.toml"]
```

Run with Docker:
```bash
docker run -p 3000:3000 -v /path/to/config.toml:/etc/syntaxis-api/config.toml -v /path/to/data:/data syntaxis-api
```

## Configuration Schema

| Setting | Type | Required | Environment Variable | Notes |
|---------|------|----------|----------------------|-------|
| `host` | string | Yes | `LIFECYCLE_API_HOST` | Server bind address |
| `port` | u16 | Yes | `LIFECYCLE_API_PORT` | Server port number |
| `database_path` | string | Yes | `LIFECYCLE_API_DATABASE_PATH` | Path to SQLite database file |
| `cors_enabled` | bool | Yes | `LIFECYCLE_API_CORS_ENABLED` | Enable CORS headers (true/false) |
| `log_level` | string | Yes | `LIFECYCLE_API_LOG_LEVEL` | trace/debug/info/warn/error |

## Usage Examples

### Local Development

```bash
./syntaxis-api --config ~/config/local.toml
```

### Remote Server (Environment Variables Override)

```bash
LIFECYCLE_API_HOST=0.0.0.0 LIFECYCLE_API_PORT=8080 LIFECYCLE_API_DATABASE_PATH=/data/prod.db \
./syntaxis-api --config /etc/syntaxis-api/prod.toml
```

### Testing

```bash
./syntaxis-api --config /tmp/test-config.toml
```

### systemd Service

Create `/etc/systemd/system/syntaxis-api.service`:

```ini
[Unit]
Description=Lifecycle API Server
After=network.target

[Service]
Type=simple
User=lifecycle
ExecStart=/usr/local/bin/syntaxis-api --config /etc/syntaxis-api/config.toml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable syntaxis-api
sudo systemctl start syntaxis-api
```

## Health Check

```bash
curl http://localhost:3000/api/health
```

## API Endpoints

All endpoints are relative to `/api`.

### Health Check
- `GET /health` - Server health status

### Projects
- `POST /projects` - Create project
- `GET /projects` - List projects
- `GET /projects/:id` - Get project
- `PUT /projects/:id` - Update project
- `DELETE /projects/:id` - Delete project

### Phases
- `GET /projects/:id/phases` - Get current phase
- `POST /projects/:id/phases/transition` - Transition to next phase
- `GET /projects/:id/phases/history` - Get phase history

### Checklists
- `GET /projects/:id/checklists` - Get all checklists
- `GET /projects/:id/checklists/phases/:phase` - Get checklist for phase
- `POST /projects/:id/checklists` - Add checklist item
- `PUT /projects/:id/checklists/items/:item_id` - Update checklist item

### Security
- `GET /projects/:id/security` - Get security assessment
- `POST /projects/:id/security/assess` - Run security assessment

### Status
- `GET /projects/:id/status` - Get project status

### Tools
- `GET /projects/:id/tools` - List tools
- `POST /projects/:id/tools/:name/enable` - Enable tool
- `POST /projects/:id/tools/:name/disable` - Disable tool

## Database

### SQLite Database

The API uses SQLite for data persistence. The database file is created automatically on first run at the path specified in configuration.

### Database Path

Paths can be absolute or relative:
- **Absolute**: `/var/lib/lifecycle/data.db`
- **Relative**: `./data/project.db` (relative to working directory)

### Directory Creation

The parent directory for the database file is created automatically if it doesn't exist.

## Logging

Logging uses the `tracing` crate with `tracing-subscriber` for output.

### Log Levels

- `trace` - Very detailed diagnostic information
- `debug` - Detailed debugging information
- `info` - General informational messages (default)
- `warn` - Warning messages
- `error` - Error messages only

### Setting Log Level

In configuration file:
```toml
[server]
log_level = "debug"
```

Or via environment variable:
```bash
LIFECYCLE_API_LOG_LEVEL=debug ./syntaxis-api --config config.toml
```

## PAP Compliance

This configuration system follows **Project Agnostic Practice (PAP)** principles:

✅ **Explicit configuration** - Configuration file path must be provided via CLI
✅ **No project-specific paths** - Works anywhere with any config file
✅ **Configuration-driven** - All settings in TOML file or environment variables
✅ **Environment variable overrides** - Runtime customization
✅ **Clean error handling** - Exact configuration errors with file path information
✅ **No hardcoded defaults** - All settings must be explicitly configured
✅ **Portable** - Works across any environment with explicit config

## Troubleshooting

### Missing Configuration File

**Error**: `Failed to read config file "...": No such file or directory`

**Solution**: Pass valid config file path:
```bash
./syntaxis-api --config /path/to/config.toml
```

### Invalid TOML Syntax

**Error**: `Failed to parse TOML config from "...": ...`

**Solution**: Check TOML file syntax and try online TOML validator

### Database Directory Not Writable

**Error**: `Failed to create database directory: Permission denied`

**Solutions**:
1. Check directory permissions: `ls -la /path/to/dir`
2. Create directory manually: `mkdir -p /path/to/data`
3. Change ownership: `sudo chown user:group /path/to/data`

### Port Already in Use

**Error**: `Failed to bind to 0.0.0.0:8080`

**Solutions**:
1. Check what's using the port: `lsof -i :8080`
2. Use different port in config file
3. Override via environment variable: `LIFECYCLE_API_PORT=9000 ./syntaxis-api --config config.toml`

### Help Command

```bash
./syntaxis-api --help
```

## Building

```bash
cargo build -p syntaxis-api --release
```

Binary location: `target/release/syntaxis-api`

## Testing

```bash
cargo test -p syntaxis-api
```

## Code Quality

```bash
cargo fmt -p syntaxis-api
cargo clippy -p syntaxis-api --all-targets
```

## See Also

- `config.rs` - Configuration module implementation
- `src/main.rs` - Server entry point and CLI argument handling