ImageApi/.specify/memory/constitution.md

ImageApi Constitution

Core Principles

I. Layered Architecture

All features MUST follow the established layered architecture:

• HTTP Layer (main.rs, feature modules): Route handlers, request parsing, response formatting. No direct database access.
• Service Layer (files.rs, exif.rs, memories.rs, etc.): Business logic. No HTTP-specific types.
• DAO Layer (database/ trait definitions): Trait-based data access contracts. Every DAO MUST be defined as a trait to enable mock implementations for testing.
• Database Layer (Diesel ORM, schema.rs): Concrete Sqlite*Dao implementations. All queries traced with OpenTelemetry.

New features MUST NOT bypass layers (e.g., HTTP handlers MUST NOT execute raw SQL). Actix actors are permitted for long-running async work (video processing, file watching) but MUST interact with the DAO layer through the established trait interfaces.

II. Path Safety (NON-NEGOTIABLE)

All user-supplied file paths MUST be validated against BASE_PATH using is_valid_full_path() before any filesystem operation. This prevents directory traversal attacks.

• Paths stored in the database MUST be relative to BASE_PATH.
• Paths passed to external tools (ffmpeg, image processing) MUST be fully resolved absolute paths.
• Extension detection MUST use the centralized helpers in file_types.rs (case-insensitive). Manual string matching on extensions is prohibited.

III. Trait-Based Testability

All data access MUST go through trait-based DAOs so that every handler and service can be tested with mock implementations.

• Each DAO trait MUST be defined in src/database/ and require Sync + Send.
• Mock DAOs for testing MUST live in src/testhelpers.rs.
• Integration tests against real SQLite MUST use in-memory databases via in_memory_db_connection() from database::test.
• Handler tests MUST use actix_web::test utilities with JWT token injection (using Claims::valid_user() and the test_key secret).
• New DAO implementations MUST include a #[cfg(test)] constructor (e.g., from_connection) accepting an injected connection.

IV. Environment-Driven Configuration

Server behavior MUST be controlled through environment variables loaded from .env files. Hard-coded paths, URLs, or secrets are prohibited.

• Required variables MUST call .expect() with a clear message at startup so misconfiguration fails fast.
• Optional variables MUST use .unwrap_or_else() with sensible defaults and be documented in README.md.
• Any new environment variable MUST be added to the README environment section before the feature is considered complete.

V. Observability

All database operations and HTTP handlers MUST be instrumented with OpenTelemetry spans via the trace_db_call helper or equivalent tracing macros.

• Release builds export traces to the configured OTLP endpoint.
• Debug builds use the basic logger.
• Prometheus metrics (imageserver_image_total, imageserver_video_total) MUST be maintained for key counters.
• Errors MUST be logged at error! level with sufficient context for debugging without reproducing the issue.

Technology Stack & Constraints

• Language: Rust (stable toolchain, Cargo build system)
• HTTP Framework: Actix-web 4
• ORM: Diesel 2.2 with SQLite backend
• Auth: JWT (HS256) via jsonwebtoken crate, bcrypt password hashing
• Video Processing: ffmpeg/ffprobe (CLI, must be on PATH)
• Image Processing: image crate for thumbnails, kamadak-exif for EXIF extraction
• Tracing: OpenTelemetry with OTLP export (release), basic logger (debug)
• Testing: cargo test, actix_web::test, in-memory SQLite

External dependencies (ffmpeg, Ollama) are optional runtime requirements. The server MUST start and serve core functionality (images, thumbnails, tags) without them. Features that depend on optional services MUST degrade gracefully with logged warnings, not panics.

Development Workflow

• cargo fmt MUST pass before committing.
• cargo clippy warnings MUST be resolved or explicitly suppressed with a justification comment.
• cargo test MUST pass with all tests green before merging to master.
• Database schema changes MUST use Diesel migrations (diesel migration generate), with hand-written SQL in up.sql and down.sql, followed by diesel print-schema to regenerate schema.rs.
• Features MUST be developed on named branches (###-feature-name) and merged to master via pull request.
• File uploads MUST preserve existing files (append timestamp on conflict, never overwrite).

Governance

This constitution defines the non-negotiable architectural and development standards for the ImageApi project. All code changes MUST comply with these principles.

• Amendments: Any change to this constitution MUST be documented with a version bump, rationale, and updated Sync Impact Report.
• Versioning: MAJOR for principle removals/redefinitions, MINOR for new principles or material expansions, PATCH for wording clarifications.
• Compliance: Pull request reviews SHOULD verify adherence to these principles. The CLAUDE.md file provides runtime development guidance and MUST remain consistent with this constitution.

Version: 1.0.0 | Ratified: 2026-02-26 | Last Amended: 2026-02-26