Getting Started
Getting Started
Prereqs, setup, and local configuration you can reuse.
Jump hereKnowledge Base
Documentation
A practical notebook of what I am actively building, why those choices were made, and how we keep systems usable as experiments move into stable flow.
Core Architecture
Core Architecture
How the platform layers, data boundaries, and flow boundaries fit together.
Jump hereIntegrations
Integrations
Supabase, Clerk, Stripe, worker, and cache patterns in practice.
Jump hereSecurity & Scale
Security & Scale
Trust boundaries, monitoring, and reliability practices.
Jump hereDocs map
Use this as a fast map when you need exact implementation context.
Start here
Prerequisites
Get local copy running
Installation
Secrets and service keys
Configuration
Vercel-ready path
Deployment
Layered model
Architecture Overview
Org-level safety
Multi-tenancy
Clerk + context
Authentication
State that lasts
Database Model
RLS and org isolation
Supabase Setup
Identity boundaries
Clerk Access
Async execution
Trigger.dev Workflows
Safety and speed
Upstash Cache
Trust, logs, resilience
Security and Scale
Active lanes
What we are working on as I write this
In progressZalaStack core lab notes
In progressFRAME YYC content and execution workflows
In progressOwned Cloud operations and reporting reliability
In progressCalgary Compute Lab infrastructure experiments
Getting started
Before diving in, make sure your environment and service accounts are set so the local path matches the public-safe model used on this site.
- Use Node.js 18+ and pnpm for local installs.
- Create the service projects you plan to connect (Supabase and Clerk included).
- Keep credentials in a local environment file and out of source control.
Prerequisites
Before you begin:
- Node.js 18+ and pnpm installed
- Supabase account and project
- Clerk application configured
- Stripe account for webhook path
Installation
Clone and install dependencies:
git clone https://github.com/mizoz/zalastack-website.git
cd zalastack-website
pnpm installConfiguration
Copy environment values and configure core services:
cp .env.example .env.local
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
CLERK_SECRET_KEY=your_clerk_secret
STRIPE_SECRET_KEY=your_stripe_secret
STRIPE_WEBHOOK_SECRET=your_webhook_secret
TRIGGER_DEV_SECRET_KEY=your_trigger_key
UPSTASH_REDIS_REST_URL=your_upstash_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_tokenCore architecture
Design goal is to keep flow clear and failure-safe:
- Control layer with explicit rules and escalation paths.
- Workflow layer for intake, routing, execution, and review.
- Service layer for APIs and external integrations.
- Observability layer for logs and checkpoints.
Architecture overview
Control layer first, then workflow, then service and observability layers. If you can explain each layer to your future self, the system is mature enough to ship.
Multi-tenancy with org_id
Scope all critical records by `org_id`, and enforce boundaries in policies and server-side reads to avoid cross-tenant drift.
Authentication and authorization
Clerk handles identity and context so access checks are explicit and repeatable. Protected routes should fail fast when context is missing.
Database patterns
Use predictable schemas for state transitions and events so workflows remain inspectable in time order.
Integrations
Supabase
- Row-level policies with organization isolation
- Structured event tables for operational memory
- Storage and auth as foundational primitives
Clerk
- Protected routes with explicit org context
- Role and permission boundaries
- Stable session behavior for internal tools
Active integration notes
- Supabase for data, auth, and policy-driven records.
- Clerk for org-aware identity boundaries.
- Trigger.dev for idempotent queue-driven jobs.
- Upstash for cache and rate controls.
Billing and webhook strategy
Stripe is used where transactional events need durable and auditable handoff into background jobs or internal logs.
Trigger.dev workflows
- Route long-running operations to async jobs.
- Keep retries idempotent and state-aware.
- Track completion state and failure outcomes.
Cache and rate controls
Upstash provides lightweight control on endpoints and metadata checks without adding heavy infrastructure overhead.
Deployment
Deploy through Vercel branches and use environment-specific previews for validation. Keep infra config in the project and rotate shared credentials on major changes.
Security and scale
- Row-level security and request context checks are treated as default policy.
- Rate limiting and logs are first-class, not optional.
- Recovery flows are explicit so one failure is visible, not invisible.
What to do next
Move to the operational layer or back to the lab notes to keep this build evolving.