Table of Contents¶

Source of truth for Judge.me engineering: system architecture, codebase, processes, and development guidelines.

📂 Where to Add Docs¶

docs/
├── onboarding/              # Getting started guides for new devs
├── architecture/            # System design, data models, how things connect
│   ├── flows/               # Request flows and sequence diagrams
│   └── widgets/             # Storefront widget architecture
├── domains/                 # Business domain deep dives (reviews, orders, etc.)
├── guides/                  # How-to guides for dev tasks
│   ├── ops/                 # Common operations (logs, deploy, DB access)
│   └── setup-integrations/  # Third-party integration setup
├── processes/               # Team processes and standards
│   ├── prs_and_deploy/      # PR workflow, deploy, changelog
│   └── incidents/           # Postmortems
├── reference/               # API docs, conventions, glossary
└── _archived/               # Deprecated platform docs

Rule of thumb: Cross-repo knowledge goes here. Repo-specific docs go in .docs/ within that repo. See judgeme/.docs/ for the core repo.

👋 New here? Start with Onboarding¶

Get your local environment running and learn the basics of the product and codebase.

Document	When to read
What is Judge.me?	Day 1 — understand the product
Local Setup	Day 1 — get the app running
Shopify Extensions Setup	When working on Shopify extensions
Frontend Server Setup	When working on the frontend server
First Week Guide	Curated reading path for your first week
Access Checklist	Day 1 — accounts and tools

🏗️ System Architecture¶

How the system is built — repos, infrastructure, data models, and how services connect.

Document	What it covers
System Overview	Repos, tech stack, infrastructure, request flow
Data Model	Postgres tables, MongoDB collections, relationships
Shopify Integration	OAuth, webhooks, API, theme code

🧩 Widgets¶

How storefront review widgets are rendered, published, and served to merchant stores.

Document	What it covers
Storefront Widget	Widget rendering, publishing, metafields

🔀 Flows¶

Step-by-step traces of critical request paths and visual sequence diagrams.

Document	What it covers
Common Flows	Key code paths walked through end-to-end
Review Request Emails	Review request emails end-to-end
Sequence Diagrams	Visual flow diagrams

🔍 Deep Dives by Domain¶

Each domain covers a major business area of Judge.me — the core data, rules, and workflows around a specific concept.

Document	What it covers
Reviews	Sources, verification, curation, scoring
Orders & Line Items	Status machine, review request scheduling
Products & Groups	Bundles, product groups, shop product
Reviewers	Roles, authentication, anonymous reviewer
Settings Reference	Key settings by category
Coupons, Rewards & Referrals	Coupon types, discount mechanics, referral flow, plan gating
Review Import	CSV import, AliExpress (AERI), Etsy sync, Google Business, limitations
Q&A	Questions and answers system
Locales & Multi-Languages	Multi-language emails, widget sorting, locale settings
Medals & Badges	Medal types, tier thresholds, recalculation, trust badges
Review Site	Eligibility, store pages, search, referral tracking, offboarding

🔌 Integrations¶

Document	What it covers
Integrations Overview	Integration architecture, two patterns (catalog vs partner), categories, multiplexed settings
Review Syndication	Google Shopping, Google XML, Bing, TikTok Shop, Meta syndication
Marketing & Automation	Klaviyo, AfterShip, Shopify Flow, Zapier, Slack

📖 Guides¶

Practical how-to docs for common development tasks, testing, and working with specific technologies.

Document	What it covers
Backend Testing	RSpec, test patterns, best practices
Frontend Testing	Cypress, Vitest, Web Vitals, selectors
Shopify Theme App Extensions	App blocks, embeds, deployment
Shopify Web Pixels	Order tracking, access scopes, pixel creation
Performance Bottlenecks	Known bottlenecks and config flags
Performance Diagnostics	Chrome DevTools diagnostics
Widget Revamp Contributing	Widget v4 dev setup, conventions, design system

🔌 Setup Integrations¶

Local setup instructions for third-party services (OAuth, payments, marketing).

Document	What it covers
Google OAuth Setup	GCP console setup, credentials, ENV
Klaviyo Setup	OAuth app overview, local setup
Stripe Setup	Local Stripe setup for dev

🛠️ Common Operations¶

Accessing environments, querying logs, and connecting to databases.

Document	What it covers
Accessing Environments	Staging, production, kubectl, SSO
Production Logs	OpenSearch, Athena, log queries
Redshift Querying	Data warehouse access and queries
Kubernetes Deployment	Deploying a new server with K8s
MongoDB Access	MongoDB Atlas connection and access

📋 Processes¶

Team standards, workflows, and checklists — how we ship code and handle incidents.

Document	What it covers
Contributing to Docs	How to add or update docs in this repo
Development Practices	Coding standards and PR practices
Definition of Done	Checklist before closing a task
Change Management	PR approvals, Wiz scanning, hotfixes
Database Change Approval	Pre-approval for DB changes
Bug Investigation Playbook	Steps for investigating bugs
Bug Priority Guidelines	Priority levels and SLAs
QA Strategies	Lean QA, dev ownership
Engineering Refinement Playbook	Refinement sessions process
Epic Owner Playbook	Epic ownership responsibilities
Code Freeze Process	Code freeze rules and exceptions

🚀 PRs & Deploy¶

PR workflow, deploy process, changelogs, and CI/CD pipelines.

Document	What it covers
Deployable PR Workflow	Staging deploy via PR labels
Deploy Notes	How to write deploy notes
Changelog Writing	Changelog format and conventions
Deployment Troubleshooting	How to solve failed deploys
Auto-rebase	How auto-rebase works and what to do
Frontend Deploy Workflows	Frontend repos CD flow diagrams
TAE CI/CD	Theme App Extension CI/CD process

🚨 Incidents¶

Postmortem process and templates for production incidents.

Document	What it covers
Postmortem Template	Postmortem template and process

📚 Reference¶

Lookup material — API specs, coding conventions, glossary, and security guidelines.

Document	What it covers
API Overview	Public REST API and OpenAPI spec
Coding Conventions	Team standards
Glossary	Domain terminology
Security Guidelines	Security best practices

🗄️ Archived¶

Docs for platforms and features no longer actively supported. See _archived/README.md.