syntaxis/core/crates/api

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

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

Configuration File Format

Create a TOML configuration file:

[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:

# 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:

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

Run:

./syntaxis-api --config ~/.config/syntaxis-api/dev.toml

Production Configuration

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

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

Run:

./syntaxis-api --config /etc/syntaxis-api/prod.toml

Docker Configuration

Create ./config/docker.toml:

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

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:

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

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

Remote Server (Environment Variables Override)

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

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

systemd Service

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

[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:

sudo systemctl daemon-reload
sudo systemctl enable syntaxis-api
sudo systemctl start syntaxis-api

Health Check

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:

[server]
log_level = "debug"

Or via environment variable:

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:

./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

./syntaxis-api --help

Building

cargo build -p syntaxis-api --release

Binary location: target/release/syntaxis-api

Testing

cargo test -p syntaxis-api

Code Quality

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