Concepts & Architecture

This section explores the core concepts and design decisions that make define.wtf work. Whether you're an admin configuring your workspace or a developer integrating with define.wtf, understanding these concepts will help you get the most out of the platform.

Key Topics

Multi-Tenancy

Every organization has its own isolated workspace, dictionary, and data. Learn how define.wtf keeps your team's data separate from others and how tenants are identified and resolved.

Read: Multi-Tenancy

Roles and Permissions

define.wtf uses role-based access control (RBAC) with four roles: Viewer, Editor, Admin, and Owner. Each role has cumulative permissions. Understand what each role can do and how permissions work.

Read: Roles and Permissions

Search Architecture

Finding the right acronym fast is crucial. define.wtf uses a four-stage search pipeline combining full-text search, fuzzy matching, and relevance scoring to deliver accurate results instantly.

Read: Search Architecture

Content Moderation

Keeping your dictionary professional and family-friendly. define.wtf uses automated profanity filtering with support for leetspeak and unicode evasion detection, plus per-tenant custom blocklists.

Read: Content Moderation

Audit Trail

Every mutation (create, edit, delete) is logged with full context including who, what, when, and why. This supports compliance requirements and helps you track changes.

Read: Audit Trail

Design Principles

1. Data Isolation

All data is scoped by tenant. Every database query includes a tenant filter to ensure teams never see each other's data.

2. Gradual Permissions

Roles are hierarchical: each level includes all permissions of lower levels, plus new ones. This makes role assignment intuitive and flexible.

3. Performance First

Features like full-text search and fuzzy matching are designed to work instantly, even with thousands of acronyms. Caching and indexing optimize response times.

4. Compliance Ready

Audit logging and structured activity tracking support enterprise requirements like SOC 2, HIPAA, and ISO 27001.

5. Open Integrations

Webhooks, APIs, and standards like SCIM and OIDC make define.wtf work with your existing tools and workflows.

For Different Audiences

If You're an Admin

Start with these concepts:

1. Multi-Tenancy — Understand your workspace isolation
2. Roles and Permissions — Manage team access
3. Content Moderation — Configure filtering policies
4. Audit Trail — Monitor activity

If You're a Developer

These concepts are most relevant:

1. Search Architecture — Understand search behavior for integrations
2. Multi-Tenancy — Important for API calls
3. Audit Trail — What events trigger webhooks

If You're an End User

You might be interested in:

1. Roles and Permissions — What can you do?
2. Search Architecture — How to find terms effectively
3. Content Moderation — What content is allowed

Architecture Overview

High-Level Flow

User Request
    ↓
Authentication (SSO or Email/Password)
    ↓
Tenant Resolution (which team?)
    ↓
Permission Check (can user do this?)
    ↓
Business Logic (create/edit/search/delete)
    ↓
Audit Log (record the change)
    ↓
Webhook (notify external systems)
    ↓
Response (200 OK, 404 Not Found, etc.)

Core Components

1. Tenant Resolution — Identifies which team the user belongs to
2. Authentication — Verifies user identity (SSO or email)
3. Authorization — Checks user's permissions
4. Search Engine — Indexes and searches acronyms
5. Cache Layer — Optimizes performance
6. Audit System — Records all mutations
7. Webhook Dispatcher — Sends real-time events to external systems

Data Model Highlights

Tenants

Each organization has one tenant with:

• Unique ID and URL slug
• Organization name and branding
• Settings and integrations
• All workspace data scoped by this ID

Users

Team members with:

• Email (unique per tenant)
• Role (Viewer, Editor, Admin, Owner)
• Profile data (name, avatar)
• Authentication method (SSO or email/password)

Acronyms & Definitions

• Acronyms — The terms you're defining (OKR, KPI, etc.)
• Definitions — Multiple user-contributed definitions per acronym
• Primary Definition — The highest-voted definition (shown by default)
• Votes — Team members can upvote/downvote definitions

Categories & Tags

• Categories — Organize acronyms by department or topic (e.g., "Finance", "Engineering")
• Tags — Additional labels for filtering and discovery

Workflows

Adding a New Acronym

User types acronym + definition
    ↓
Profanity check (scanned for blocked words)
    ↓
Acronym created (stored in database)
    ↓
Definition created and linked
    ↓
Search index updated (added to FTS5 index)
    ↓
Webhook fired (external systems notified)
    ↓
Audit logged (recorded who, what, when)

Searching for an Acronym

User enters search query
    ↓
Query escaped (SQL injection prevention)
    ↓
FTS5 search (full-text search index lookup)
    ↓
Fuzzy matching (typo tolerance)
    ↓
Fuse.js client-side filtering (in UI)
    ↓
Results ranked by relevance
    ↓
Results returned (with metadata)

User Login via SSO

User clicks "Sign in with Company"
    ↓
Redirect to IdP (Okta, Azure AD, etc.)
    ↓
User authenticates at IdP
    ↓
IdP redirects to define.wtf with code
    ↓
define.wtf exchanges code for token
    ↓
Check if user exists (match by email)
    ↓
Create new user if needed (first login)
    ↓
Assign role (from SCIM groups or default)
    ↓
Create session
    ↓
Redirect to dashboard

Why These Design Decisions?

Why Multi-Tenancy?

• Allows one define.wtf deployment to serve many organizations
• Ensures complete data isolation and privacy
• Allows each team to maintain their own dictionary
• Simpler than per-organization deployments

Why Role-Based Access Control?

• Flexible permission model that scales from small to large teams
• Intuitive: higher roles include lower role's permissions
• Easy to audit: track who has what access
• Supports granular policies (e.g., users can edit own definitions only)

Why Full-Text Search + Fuzzy Matching?

• FTS5 is fast and handles complex queries efficiently
• Fuzzy matching forgives typos (e.g., "ORK" → "OKR")
• Combination catches what users are looking for
• Simple to explain and understand

Why Audit Everything?

• Compliance requirement for most enterprises
• Troubleshooting: understand what changed and why
• Security: detect suspicious activity
• Transparency: users see who made changes

Performance Considerations

Search Performance

• FTS5 indexes are updated in real-time
• Fuzzy matching has a 2-character distance threshold
• Client-side search (Fuse.js) filters results without additional API calls
• Caching reduces repeated lookups

Scalability

• define.wtf is designed to scale to thousands of users and tens of thousands of acronyms
• Database indexes optimize query performance
• Caching layer reduces database load
• Webhook dispatching is fire-and-forget (doesn't block user requests)

Availability

• define.wtf runs on Vercel (auto-scaling)
• Database backups and replication
• Graceful degradation if search is unavailable

Security & Compliance

• Data encryption — All data in transit (TLS) and at rest (encrypted database)
• Access control — Tenant isolation and permission checks
• Audit logging — All mutations recorded for compliance
• Signature verification — Webhook and Slack integration signatures verified
• SCIM security — Token-based authentication
• SSO security — OIDC standard compliance

Ready to dive deeper? Start with the topic that interests you most!