artcraft/.claude/rules/code-style.md

Code Style

Rust

• Two spaces for indentation (not four)
• No minimum supported Rust version; use latest stable features freely
• #[macro_use] extern crate serde_derive; is used in binary crates; library crates use use serde_derive::{Serialize, Deserialize};
• Never use println! or eprintln! outside of tests; use log crate macros (info!, warn!, error!, debug!, trace!) instead
• Use anyhow::Result / AnyhowResult for fallible functions in application code; new database queries should use Result<T, sqlx::Error> instead
• SQLx: MySQL queries belong in the mysql_queries crate. Do NOT write sqlx::query! / sqlx::query() in application/service crates (e.g. storyteller-web, which has zero direct SQLx queries) — add or reuse a function in mysql_queries and call it. The compile-time query! / query_as! macro conventions for that crate are documented in crates/schema/database/mysql_queries/CLAUDE.md.
• Enum Display/Debug: use impl_enum_display_and_debug_using_to_str! macro, not derive_more::Display (CLion doesn't understand it)
• Fields that are optional use the maybe_ prefix: maybe_creator_user_token, maybe_prompt_token
• When implementing fmt::Display for error types, use the pattern: write!(f, "{:?}", self)

File Layout (Top-to-Bottom Reading Order)

Organize code so a human reading top-to-bottom encounters the most important things first and can drill down into details only when curious. Think of it like a newspaper: headline first, then the story, then the fine print.

Ordering within a file

1. Constants at the top, right after imports.
2. The primary public type (the main struct/enum the file is about) comes next. A reader opening this file should immediately see what it defines.
3. Supporting/subordinate types (sub-structs, helper enums, serialization DTOs) go below the primary type, not above it. Ask: "Would a reader need to know this type exists before seeing the main type?" — if no, push it down.
4. Type ordering for API types: Request, then Response (success), then Error.
5. impl blocks after their type definitions.

Ordering within an impl block

1. Constructors (new, from_*, builder) at the top.
2. Public methods next — these are the main entry points a reader cares about.
3. Private helper methods below public methods.
   • Among helpers: place "meaty" helpers (substantial logic, direct continuations of the public entry point) above "leaf" helpers (small formatters, simple lookups).
   • A method that calls another method in the same file should appear above the method it calls. This lets readers follow the call chain downward.

Ordering within test modules

Put test cases first, helpers last. A reader opening a test file should immediately see what is being tested before how the test machinery works.

1. Imports
2. Constants (test IDs, URLs, fixture data) — small context that tests reference
3. Test functions or sub-modules grouped by category
4. Helper functions (builders, pipeline runners, assertions)

Group related tests into sub-modules (mod pricing_tests { ... }) when a category has 2+ tests. Don't create a sub-module for a single test. Keep nesting to two levels max (mod tests { mod category { ... } }). Shared helpers go in the parent module so sub-modules can reach them via use super::*.

Naming

• Handler functions: {verb}_{noun}_handler (e.g. get_health_check_handler, login_handler)
• Error enums: {Feature}Error (e.g. FalWebhookError, HealthCheckError)
• Request/response structs: {Action}Request, {Action}Response, {Action}SuccessResponse
• Path params: {Action}PathInfo
• Builder structs: {Thing}Builder with set_ prefixed setters and a build() method

Imports

• Group imports: std, external crates, internal workspace crates, crate:: imports
• Prefer use imports over inline fully-qualified paths. Inline qualification is acceptable only for genuine one-off references where adding an import would be noise, or for types that collide with std prelude names (Result, Option, Error). If you reference a symbol more than once, always import it.
• Prefer specific imports over wildcards, except in api_doc.rs and test modules
• When two crates export a type with the same name, alias with a suffix describing the source crate: use enums::...::CommonResolution as CommonResolutionEnum; use artcraft_router::...::CommonResolution as CommonResolutionRouter; This avoids long fully-qualified paths in function signatures and bodies.

MySQL

• MySQL tables: primary key id columns must be BIGINT(20) UNSIGNED. Do not use signed IDs.
• Always create tables with ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin.

TypeScript / Frontend

• TypeScript with React, Vite, Zustand, Three.js
• Nx monorepo under crates/frontend/
• Two spaces for indentation