Case Study · Operations & Multi-Tenant SaaS

Veyra

Veyra is a multi-tenant feedback and review-management platform designed for organizations to collect public feedback through QR-based entry points, moderate responses, publish approved reviews, manage subscriptions, and operate the platform through administrative and developer tooling.

As System Architect and Lead Developer at Nyebe Creations Studio, I designed the application structure, tenant data boundaries, custom application RBAC, developer observability dashboard, consent-gated first-party analytics, and portable production runtime architecture.

Domain: Operations (Multi-Tenant SaaS)
My Role: System Architect + Lead Developer
Organization: Nyebe Creations Studio
Lifecycle: Active Development · Appwrite Sites Production
Core Stack: React + TypeScript · TanStack Start / Router / Query · Appwrite · Tailwind CSS
DevOps / Runtime: Appwrite Sites SSR · Docker · Kubernetes · Appwrite Functions

Overview & Architectural Focus

While public QR code scanning serves as the initial customer interaction point, Veyra is fundamentally a multi-tenant SaaS platform built for security, operational visibility, data governance, and tenant isolation.

The primary engineering effort was focused on building a robust backend service architecture, explicit tenant data boundaries, custom Role-Based Access Control (RBAC), developer operations analytics, consent-gated first-party analytics, and reproducible runtime deployment profiles.

System Scope Product development + system architecture + security boundaries + developer operations.

Engineering Focus Full-Stack · Architecture · DevOps · Infrastructure · Data

Central System Narrative Flow

The complete end-to-end Veyra architecture connects public customer feedback entry with tenant management, security enforcement, developer analytics, and runtime deployment profiles:

Central system narrative flow diagram for Veyra (dark theme) — Central System Narrative Flow: End-to-end architecture connecting customer QR entry points to multi-tenant operations, RBAC, and runtime deployment profiles.

Ownership Context & Technical Leadership

Veyra is a team project developed under Nyebe Creations Studio. In my role as System Architect and Lead Developer, I provided technical direction across system design while directly implementing core backend services and security logic.

Architecture & Security Ownership Designed multi-tenant data boundaries, RBAC role structures, permission verification middlewares, and audit logging pipelines.

Developer Operations Leadership Engineered GitHub Actions CI/CD workflows, containerization strategies, and environment synchronization tools for developer workflow efficiency.

Full-Stack Hands-On Contribution Implemented frontend management views, moderation pipelines, QR feedback submission interfaces, and API integrations.

Multi-Tenant Architecture

Veyra utilizes a shared application and database architecture with tenant-aware record scoping. Every organization resource is bound to a verified tenant identifier, ensuring strict resource scoping across all platform queries.

Tenant-scoped data entities:

Organization Members: Users registered under a specific organization.
Feedback Submissions: Pending and archived customer submissions.
Reviews: Moderated, approved, or rejected public review records.
Role Definitions: Organization-specific custom role templates.
Subscription Records: Billing status, tier limits, and feature flags.

Multi-tenant architecture diagram for Veyra (light theme) — Multi-Tenant Architecture: Resource scoping and tenant-bound entity relationships across organization members, submissions, and reviews.

Multi-tenant architecture diagram for Veyra (dark theme) — Multi-Tenant Architecture: Resource scoping and tenant-bound entity relationships across organization members, submissions, and reviews.

Database Isolation Model

Dedicated tenant databases are an optional, platform-controlled isolation tier rather than the default. The initial implementation is complete with platform-controlled request/approval control-plane records, database provisioning, schema verification, authenticated binding resolution, data migration/export, and guarded retirement tooling. Activation remains subject to release gates for affected data flows and erasure behavior before claiming full active per-tenant database isolation in production.

DEFAULT: Shared Tenant-Aware Data All organization data resides within shared collection structures guarded by explicit tenant ID scoping and backend permission rules.

IMPLEMENTATION FOUNDATION COMPLETE: Dedicated Data Isolation Platform-controlled request/approval control plane, schema verification, tenant binding, migration/export, and retirement tooling are implemented under active release gates.

Database isolation model diagram for Veyra (light theme) — Database Isolation Model: Shared tenant-aware data architecture with optional platform-controlled dedicated database tier.

Database isolation model diagram for Veyra (dark theme) — Database Isolation Model: Shared tenant-aware data architecture with optional platform-controlled dedicated database tier.

Core Tenancy Principle

In Veyra, a user request is never authorized simply because the target record exists in the system. The platform evaluates identity, organization context, and specific role capabilities simultaneously before granting access:

Core tenancy principle diagram for Veyra (dark theme) — Core Tenancy Principle: Multi-point authorization evaluation connecting identity, organization context, and permission templates.

Custom Role-Based Access Control (RBAC)

Veyra implements a multi-layered security and authorization architecture combining server-side application logic, Appwrite document permissions, and database-stored role definitions.

Role family hierarchy:

platform_owner: Global system administrator managing platform-wide tenants, custom role template definitions, billing lifecycle, and operational health.
org_admin: Organization administrator managing organization members, subscription settings, review policies, and moderation workflows using platform-defined role capabilities.
dev: Developer operations role with access to observability dashboards, developer action management, Appwrite Function health/management, and failure signal forecasting.
Configurable Role Templates: Platform-managed role templates with platform and tenant scope for fine-grained capability assignment.

RBAC layered authorization model diagram for Veyra (light theme) — Custom RBAC: Multi-layered authorization model combining authentication, server application logic, role definitions, tenant boundary enforcement, and Appwrite backend permissions.

RBAC layered authorization model diagram for Veyra (dark theme) — Custom RBAC: Multi-layered authorization model combining authentication, server application logic, role definitions, tenant boundary enforcement, and Appwrite backend permissions.

Public QR Feedback Pipeline

The public entry point for customer feedback relies on location-based QR code markers where an opaque QR slug resolves persisted organization and feedback configuration on the server, accepting anonymous submissions through validated, rate-limited public APIs without trusting a browser-supplied tenant identifier or encoding tokens in public URLs:

Public QR feedback pipeline diagram for Veyra (dark theme) — Public QR Feedback Pipeline: Customer QR entry through server-side context resolution, validation, moderation queue, and staff review outcomes.

Subscription Lifecycle & Feature Access

Organization features, usage quotas, member limits, and API access are governed by explicit subscription lifecycle management.

Key subscription capabilities:

Implemented Lifecycle Statuses: Active paid, payment pending verification, payment rejected, overdue grace period, free version active, free version expired, and subscription required.
Feature & Quota Access Gates: Dynamic checks enforcing feature availability and member limits based on active subscription state.
Payment Verification Workflow: Manual payment verification paired with automated billing lifecycle transitions, renewal reminders, grace periods, and free-version fallback.

Access Guardrails Subscription middleware automatically restricts administrative actions when an organization subscription enters expired or overdue grace states.

Developer Operations & Analytics

Veyra combines structured operational telemetry, developer read auditing, Sentry error monitoring, health/cron/function tooling, and scrubbed developer-facing diagnostics. The developer dashboard separates current actionable posture from historical trends and forecast output so resolved issues do not inflate active operational counts.

Actionable Posture & Decision Queue Tracks unresolved failures, active system posture, function health, and active operational work items.

Historical Signal Regression Renders occurrence-aware failure, security, and cron series over elapsed time buckets using linear regression via simple-statistics with sample guards and R-squared fit interpretation.

SARIMA Failure Volume Forecasting Evaluates daily failure volume using SARIMA models via the arima package (minimum 84 daily observations, 7-day weekly seasonality and horizon, evaluated with MAE/RMSE) and automatically falls back to a weekly seasonal-naive baseline if SARIMA does not improve MAE by at least 5%.

Diagnostic Redaction & Observability Integrates Sentry error monitoring alongside internal HMAC-signed observability ingestion with timestamp/nonce replay protection, developer read auditing, and strict redaction of credentials, bearer tokens, JWTs, API keys, and stack frames.

Security, Data Governance & Quality

Platform security, data handling, and release stability are managed through explicit data retention policies, consent-gated public analytics, provider fallbacks, and multi-layered quality gates.

Consent-Gated First-Party Public Analytics Records minimized public-page engagement only after explicit user choice using a separate random identifier (no authenticated identity or tenant data is collected). Retains raw events for 30 days, enforces minimum-cohort suppression (cohort ≥ 5), and generates rolling means, OLS regression, and Median/MAD anomaly evidence on published aggregates.

Structured Security Records & Data Classification Structured security and audit records log actor, action, target resource, timestamp, and organization scope while IP-derived data is contextual or hashed. Data retention follows typed classification rules with legal-hold-aware cleanup.

Transactional Email Resilience Uses an ordered Brevo primary and Resend secondary fallback workflow with fail-closed behavior when provider delivery acceptance is uncertain, preventing duplicate email dispatch.

CI, Quality Gates & Deployment Profiles

The repository uses a portable TanStack server build with Appwrite Sites SSR as the existing production profile and Docker/Kubernetes as an AWS-ready alternative. CI quality is enforced through GitHub Actions and Travis checks for lint/type/build, coverage, Playwright end-to-end testing, and self-hosted SonarQube Community quality gates, with Codecov and CodeScene providing supplementary quality evidence.

CI, quality gates, and deployment profiles diagram for Veyra (light theme) — Delivery & Deployment: GitHub Actions and Travis CI quality workflows with dual Appwrite Sites SSR and Docker/Kubernetes runtime profiles.

CI, quality gates, and deployment profiles diagram for Veyra (dark theme) — Delivery & Deployment: GitHub Actions and Travis CI quality workflows with dual Appwrite Sites SSR and Docker/Kubernetes runtime profiles.

Roadmap & Planned Features

PostHog Product Analytics Integration (PLANNED) PostHog integration is planned as a future product analytics addition to complement the existing consent-gated first-party analytics system. It is currently not present in the production dependency tree and will remain documented as planned until merged into main release.

System & Architectural Constraints

Strict Tenant Data Isolation Preventing data leaks across organization boundaries required strict middleware checks on every API request.

Public Submission Abuse Protection Public-facing QR feedback forms required rate-limiting and anti-spam protection without friction for legitimate customers.

Multi-Layered Authorization Performance Evaluating role templates, organization boundaries, and Appwrite backend permissions needed to execute efficiently without causing API latency.

DevOps & Quality Engineering Managing backend service updates across local, staging, and production environments required reproducible deployment scripts and SonarQube quality gates.

Key Technical Decisions

1. Explicit Tenant-Scoped Record Architecture & Appwrite Sites SSR

Context: Multi-tenant SaaS serving multiple organizations requiring portable runtime rendering and strict data boundaries.

Decision: Standardized on React 19 + TanStack Start and Appwrite Sites SSR, binding resource models to explicit organization IDs with application controller boundary checks.

2. Server-Side Context Resolution for QR Entries

Context: Public customers need a frictionless way to submit feedback without creating accounts or exposing organization credentials in URLs.

Decision: Resolve opaque QR slugs to persisted organization and feedback configuration on the server, accepting validated submissions through rate-limited public APIs without trusting browser-supplied tenant identifiers.

3. Actionable Developer Operations & SARIMA Signal Forecasting

Context: Maintaining operational health across services and Appwrite Functions without inflating failure counts with resolved issues.

Decision: Build an in-app developer console separating current actionable posture from historical trend regression and SARIMA daily failure volume forecasting (benchmarked against a weekly seasonal-naive baseline using MAE/RMSE).

4. Privacy-First Consent-Gated Public Analytics

Context: Measuring public feedback engagement without compromising user privacy or mixing public analytics with authenticated tenant telemetry.

Decision: Implement a consent-gated first-party analytics boundary storing minimized page interactions under random post-consent IDs, with 30-day raw event retention, minimum-cohort suppression (≥ 5), and Median/MAD anomaly evidence.

5. Multi-Layered Quality Gates & Dual Deployment Profiles

Context: Ensuring release quality across schema updates, application services, and multiple deployment targets.

Decision: Combine GitHub Actions, Travis, Playwright, Codecov, CodeScene, and self-hosted SonarQube Community quality gates with dual Appwrite Sites SSR and Docker/Kubernetes runtime profiles.

6. Transactional Email Resilience

Context: Delivering critical administrative notifications and verification emails reliably.

Decision: Implement ordered Brevo primary and Resend fallback dispatch with fail-closed rules around uncertain provider delivery acceptance to prevent duplicate mail.

Verified Qualitative Outcomes

Active Multi-Tenant Platform with Production Runtime Engineered a secure, tenant-isolated feedback SaaS on Appwrite Sites SSR with continuing security and privacy release gates.

Robust Security & Custom Role Boundaries Implemented multi-layered custom RBAC preventing unauthorized access across organization data boundaries.

Actionable Developer Observability & Forecasting Equipped developers with real-time health posture, scrubbed diagnostics, historical signal regression, and SARIMA failure volume forecasting.

Privacy-First Consent-Gated Analytics Delivered public engagement insight through cohort-guarded first-party analytics with MAD anomaly detection.

Verified CI Quality Gates Maintained high codebase reliability through SonarQube, Playwright, Codecov, and multi-runner CI checks.

Verified qualitative outcomes diagram for Veyra (light theme) — Verified Qualitative Outcomes: Platform delivery, security boundaries, developer observability, privacy-first analytics, and CI quality gates.

Verified qualitative outcomes diagram for Veyra (dark theme) — Verified Qualitative Outcomes: Platform delivery, security boundaries, developer observability, privacy-first analytics, and CI quality gates.

Lessons & Retrospective

Architecture & Authorization Boundaries First

Veyra demonstrated that establishing explicit tenant scoping, custom RBAC roles, and server-side context resolution upfront prevents security refactoring as feature sets expand.

Observability & Quality Engineering as Product Foundations

Integrating in-app developer operations, SARIMA signal forecasting, scrubbed diagnostics, and SonarQube quality gates allowed the team to maintain high operational stability and catch regressions early.