Files

Mikhail Chusavitin c295b60dd8 docs: introduce bible/ as single source of architectural truth

- Add bible/ with 7 hierarchical English-only files covering overview,
  architecture, database schemas, API endpoints, config/env, backup, and dev guides
- Consolidate all docs from README.md, CLAUDE.md, man/backup.md into bible/
- Simplify CLAUDE.md to a single rule: read and respect the bible
- Simplify README.md to a brief intro with links to bible/
- Remove man/backup.md and pricelists_window.md (content migrated or obsolete)
- Fix API docs: add missing endpoints (preview-article, sync/repair),
  correct DELETE /api/projects/:uuid semantics (variant soft-delete only)
- Add Soft Deletes section to architecture doc (is_active pattern)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-20 14:15:52 +03:00

3.1 KiB

Raw Blame History

05 — Configuration and Environment

File Paths

SQLite database (`qfs.db`)

OS	Default path
macOS	`~/Library/Application Support/QuoteForge/qfs.db`
Linux	`$XDG_STATE_HOME/quoteforge/qfs.db` or `~/.local/state/quoteforge/qfs.db`
Windows	`%LOCALAPPDATA%\QuoteForge\qfs.db`

Override: -localdb <path> or QFS_DB_PATH.

config.yaml

Searched in the same user-state directory as qfs.db by default. If the file does not exist, it is created automatically. If the format is outdated, it is automatically migrated to the runtime format (server + logging sections only).

Override: -config <path> or QFS_CONFIG_PATH.

Important: config.yaml is a runtime user file — it is not stored in the repository. config.example.yaml is the only config template in the repo.

config.yaml Structure

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"   # release | debug

logging:
  level: "info"     # debug | info | warn | error
  format: "json"    # json | text
  output: "stdout"  # stdout | stderr | /path/to/file

backup:
  time: "00:00"     # HH:MM in local time

Environment Variables

Variable	Description	Default
`QFS_DB_PATH`	Full path to SQLite DB	OS-specific user state dir
`QFS_STATE_DIR`	State directory (if `QFS_DB_PATH` is not set)	OS-specific user state dir
`QFS_CONFIG_PATH`	Full path to `config.yaml`	OS-specific user state dir
`QFS_BACKUP_DIR`	Root directory for rotating backups	`<db dir>/backups`
`QFS_BACKUP_DISABLE`	Disable automatic backups	—
`QF_DB_HOST`	MariaDB host	localhost
`QF_DB_PORT`	MariaDB port	3306
`QF_DB_NAME`	Database name	RFQ_LOG
`QF_DB_USER`	DB user	—
`QF_DB_PASSWORD`	DB password	—
`QF_JWT_SECRET`	JWT secret	—
`QF_SERVER_PORT`	HTTP server port	8080

QFS_BACKUP_DISABLE accepts: 1, true, yes.

CLI Flags

Flag	Description
`-config <path>`	Path to config.yaml
`-localdb <path>`	Path to SQLite DB
`-reset-localdb`	Reset local DB (destructive!)
`-migrate`	Apply pending migrations and exit
`-version`	Print version and exit

Installation and First Run

Requirements

Go 1.22 or higher
MariaDB 11.x (or MySQL 8.x)
~50 MB disk space

Steps

# 1. Clone the repository
git clone <repo-url>
cd quoteforge

# 2. Apply migrations
go run ./cmd/qfs -migrate

# 3. Start
go run ./cmd/qfs
# or
make run

Application is available at: http://localhost:8080

On first run, /setup opens for configuring the MariaDB connection.

OPS Project Migrator

Migrates quotes whose names start with OPS-xxxx (where x is a digit) into a project named OPS-xxxx.

# Preview first (always)
go run ./cmd/migrate_ops_projects

# Apply
go run ./cmd/migrate_ops_projects -apply

# Apply without interactive confirmation
go run ./cmd/migrate_ops_projects -apply -yes

Docker

docker build -t quoteforge .
docker-compose up -d

3.1 KiB Raw Blame History