Sitr

Sitr is a high-performance hyperlocal search engine and business directory platform built with Crystal and Kemal.

🚀 Features

• Fast & Efficient: Built on Crystal for native compiled performance.
• Modern Architecture: Kemal, Slang templates, vanilla CSS custom properties.
• Robust Role Hierarchy: Admin, Manager, Sales Rep, Verifier, and Business Owner.
• Anti-Fraud Separation of Duties: Dedicated verification queue and cash handover ledger.
• Media Optimization: Image processing and WebP conversion via libvips.
• Infrastructure Ready: Rootless containerization (Alpine 3.21) with OpenTofu & GitLab CI/CD for Google Cloud Run.

🛠️ Tech Stack

• Language: Crystal (>= 1.19.0)
• Framework: Kemal
• Database: MariaDB 11.4 / MySQL (via crystal-mysql & db)
• Cache & Sessions: Valkey 8 / Redis
• Templating: Slang
• Testing: Spec + Selenium (Browser tests)

📦 Installation

Prerequisites

• Crystal >= 1.19.0
• MariaDB 11.4+ / MySQL 8.0+
• Valkey 8+ / Redis 7.0+
• libvips (for image processing)

Setup

# Install dependencies
shards install

# Setup database
make db-setup

# Seed data
make seed

💻 Development

Start the development server:

make dev

Visit http://localhost:3000.

Testing & Linting

make test         # Run unit & integration test suite
make test-browser # Run browser E2E tests (Firefox + Geckodriver)
make test-all     # Run complete test suite
make lint         # Run Ameba and Flaw static analysis
make format       # Format codebase with Crystal formatter

📚 Specifications & Documentation

Authoritative project specifications are located in docs/:

• Architecture Specifications
• Data Models
• API Endpoints Reference
• Business Lifecycle
• User Roles & Security
• CI/CD Infrastructure

🚢 Deployment

Production deployments are automated via GitLab CI/CD on signed semantic release tags (v*.*.*).

See CI/CD Setup Guide for configuration instructions.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.