Capri DAM (Digital Asset Management)

A modern, headless Digital Asset Management platform built as a hybrid Rails monolith: server-rendered HTML shells (Hotwire/Turbo) with mounted React 19 islands, exposing both a REST API (/api/v1/**) and a GraphQL API (/graphql). Background processing runs on Sidekiq, and semantic search is powered by PostgreSQL + pgvector.

---

🛠 Tech Stack

Layer	Technology
Language	Ruby 4.0.3 (see .ruby-version)
Framework	Rails ~> 8.1
Node	22.16.0 (see .node-version), engines >=20
Frontend	React 19, MUI v9, Emotion 11, @xyflow/react, TipTap, Recharts
JS bundler	esbuild (yarn build)
Database	PostgreSQL 14 + pgvector (via the neighbor gem)
Background jobs	Sidekiq + sidekiq-throttled, Redis
Auth	Devise, Doorkeeper (OAuth2), OmniAuth Keycloak (SSO)
Storage	ActiveStorage → local / S3 / GCS / Azure Blob + CDN
API docs	rswag (OpenAPI/Swagger), SpectaQL (GraphQL)
Tests	RSpec, Jest + Testing Library, Playwright
Lint / Security	rubocop-rails-omakase, Brakeman, bundler-audit
License	Apache 2.0

---

📋 Prerequisites

Tool	Version	Notes
Ruby	4.0.3	see .ruby-version (managed via rbenv)
Node.js	22.16.0	see .node-version
Yarn	1.22.x	classic
PostgreSQL	14 + pgvector	make bootstrap installs postgresql@14
Redis	6+	required for Sidekiq & Action Cable
ImageMagick / exiv2	latest	image variants & metadata extraction

On macOS with Homebrew, make bootstrap installs these for you.

---

🚀 Getting Started

The project uses a Makefile to automate system dependencies and application configuration. Follow these steps in order.

1. Initial system bootstrap

If you are setting up on a new machine, this installs the required system libraries (Redis, rbenv, ruby-build, Node, Yarn, exiv2, pkg-config, and PostgreSQL 14) and ensures Ruby 4.0.3 is active.

make bootstrap
# After this completes, restart your terminal or run `source ~/.zshrc`
# to activate the new Ruby environment.

2. Application setup

Installs all Ruby gems and JavaScript packages, creates and prepares the database, seeds a default admin user, and initialises RSpec.

make setup

Credentials are encrypted in config/credentials.yml.enc. Supply the RAILS_MASTER_KEY (or config/master.key) before running setup.

3. Launch the development environment

Starts the Rails server, the esbuild JS watcher, and Sidekiq workers together.

make dev          # or: bin/dev

The application is available at http://localhost:3000.

---

🧪 Testing

make test               # full backend RSpec suite (prepares test DB first)
make test-frontend      # Jest unit & component tests
make test-graphql       # GraphQL endpoint request specs
make playwright-install # install Playwright browsers (one-time)
yarn playwright test    # end-to-end tests (server must be running)

Coverage

make coverage           # backend (SimpleCov) + frontend (Istanbul)
make coverage-backend   # → coverage/backend/index.html
make coverage-frontend  # → coverage-frontend/unit/index.html
make e2e                # frontend (Playwright) + backend (Coverband) E2E

---

📚 API Documentation

make api-docs           # regenerate BOTH REST (Swagger) and GraphQL (SpectaQL) docs
make swagger-docs       # REST only   → view at /api/rest
make graphql-docs       # GraphQL only → view at /api/graphql
make check-api-specs    # verify every api/v1 controller has a request spec
make check-graphql-docs # verify GraphQL SDL + HTML docs are present

A pre-commit hook (make install-hooks) runs RuboCop on staged Ruby and blocks API/GraphQL changes that ship without regenerated docs.

---

✅ Quality Gates

Concern	Command
Ruby style	bundle exec rubocop
Ruby security	bundle exec brakeman -q
Dependency CVEs	bundle exec bundler-audit check --update
Backend tests	make test
Frontend tests	yarn test --ci
E2E	yarn playwright test

---

🔧 Available Make Targets

Command	Description
make bootstrap	Install system packages and Ruby 4.0.3 (macOS/Homebrew)
make setup	Install dependencies, create & prepare the database, seed data
make dev	Start the server, JS watcher, and Sidekiq workers
make db-setup	Create and migrate the PostgreSQL database
make seed	Populate the database with the default admin user
make test	Run the full backend RSpec suite
make test-frontend	Run the Jest unit & component tests
make api-docs	Regenerate REST + GraphQL documentation
make install-hooks	Install the pre-commit lint + stale-docs hook
make clean	Wipe temporary logs and compiled asset builds
make help	Display the full list of automation targets

---

📖 Further Reading

• CONTRIBUTING.md — setup, style guides, and the testing matrix
• ARCHITECTURE.md — pointer to the full arc42 doc set in docs/architecture/
• CLAUDE.md / AGENTS.md — operating rules for AI coding assistants
• RELEASING.md — release and deployment process
• CODE_OF_CONDUCT.md — community standards

---

📄 License

Capri DAM is released under the Apache License 2.0.