Zeoel Saas Architect

Zeoel SaaS Architect

Overview

This skill provides Gohar (CEO) with a concrete blueprint for architecting a SaaS project using the Zeoel standard stack: Next.js (App Router) + Laravel (API) + PostgreSQL.

When a user describes a SaaS idea, Gohar uses this skill during Phase 2 (Sprint Planning) to ensure the project starts with the correct foundation.

The Standard SaaS Stack

┌────────────────────────────────────────────────────────────┐
│                    FRONTEND (Karar)                        │
│  Next.js 14+ (App Router, TypeScript, Tailwind, shadcn)   │
│  ├── Server Components (data fetching, SEO)               │
│  ├── Client Components (interactivity)                    │
│  ├── Server Actions (mutations)                           │
│  └── Middleware (auth redirect, tenant detection)          │
└───────────────────────┬────────────────────────────────────┘
                        │ REST API (JSON)
                        │ Auth: Laravel Sanctum
┌───────────────────────▼────────────────────────────────────┐
│                    BACKEND (Tariq)                          │
│  Laravel 11+ (PHP 8.3, Sanctum, Cashier, Horizon)          │
│  ├── Controllers (thin, validation only)                   │
│  ├── Services/Actions (business logic)                     │
│  ├── Form Requests (input validation)                      │
│  ├── Policies (authorization)                              │
│  ├── Queues via Horizon (emails, webhooks, heavy jobs)     │
│  └── Webhooks (Stripe events)                              │
└───────────────────────┬────────────────────────────────────┘
                        │
┌───────────────────────▼────────────────────────────────────┐
│                    DATABASE (Tariq + Fatima)                │
│  PostgreSQL 16+                                            │
│  ├── Core tables (users, teams, plans, subscriptions)      │
│  ├── Tenant-scoped data (global scopes)                    │
│  ├── Analytics tables (events, metrics)                    │
│  └── Redis (sessions, cache, rate limiting, queues)        │
└────────────────────────────────────────────────────────────┘

SEO-First URL Architecture (Zara)

Every SaaS project MUST define its URL structure before any code is written:

Marketing/Public Pages (SSR, fully crawlable)

/                           → Homepage (Server Component, full SEO)
/features                   → Features overview
/features/[slug]            → Individual feature page
/pricing                    → Pricing page with plan comparison
/blog                       → Blog index (paginated)
/blog/[category]            → Category index
/blog/[category]/[slug]     → Blog post
/about                      → About page
/contact                    → Contact form
/changelog                  → Product changelog
/docs                       → Documentation index
/docs/[...slug]             → Nested documentation pages

App Pages (Auth-gated, NOT indexed)

/dashboard                  → Main dashboard
/dashboard/settings         → User/team settings
/dashboard/billing          → Subscription management
/dashboard/[feature]        → Feature-specific pages
/onboarding                 → First-time user setup
/onboarding/[step]          → Onboarding steps

SEO Infrastructure Files

/sitemap.ts                 → Dynamic sitemap generation
/robots.ts                  → Robots rules (block /dashboard/*)
/manifest.ts                → PWA manifest
/opengraph-image.tsx        → Dynamic OG image generation

Sprint 0: Foundation (Always First)

Every SaaS project starts with Sprint 0. This is non-negotiable.

Sprint 0 Task List

Next.js Project Structure (Karar)

src/
├── app/
│   ├── (marketing)/           # Public pages group
│   │   ├── layout.tsx         # Marketing layout with nav + footer
│   │   ├── page.tsx           # Homepage
│   │   ├── features/
│   │   ├── pricing/
│   │   └── blog/
│   ├── (app)/                 # Authenticated app group
│   │   ├── layout.tsx         # Dashboard layout with sidebar
│   │   ├── dashboard/
│   │   └── onboarding/
│   ├── (auth)/                # Auth pages group
│   │   ├── login/
│   │   ├── register/
│   │   └── forgot-password/
│   ├── sitemap.ts
│   ├── robots.ts
│   └── layout.tsx             # Root layout (metadata, fonts)
├── components/
│   ├── ui/                    # shadcn/ui base components
│   ├── marketing/             # Marketing-specific components
│   └── dashboard/             # Dashboard-specific components
├── lib/
│   ├── api.ts                 # Laravel API client
│   ├── auth.ts                # Auth utilities
│   └── seo.ts                 # JSON-LD helpers, metadata factories
└── types/
    └── index.ts               # Shared TypeScript types

Laravel Project Structure (Tariq)

app/
├── Http/
│   ├── Controllers/Api/V1/    # Versioned API controllers
│   ├── Middleware/             # Tenant, auth, rate limiting
│   └── Requests/              # Form Request validation
├── Models/                    # Eloquent models
├── Services/                  # Business logic
├── Actions/                   # Single-purpose actions
├── Policies/                  # Authorization
├── Events/                    # Domain events
├── Listeners/                 # Event handlers
└── Jobs/                      # Queued jobs
database/
├── migrations/                # Timestamped migrations
├── seeders/                   # Dev data seeders
└── factories/                 # Test factories
routes/
├── api.php                    # API routes (versioned)
└── web.php                    # Webhook routes only

Required JSON-LD Schemas (Zara → Karar)

Every SaaS marketing site must include these structured data schemas:

// Homepage
const organizationSchema = {
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Product Name]",
  "url": "[URL]",
  "logo": "[Logo URL]",
  "sameAs": ["[social links]"]
};

// Pricing Page
const productSchema = {
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "[Product Name]",
  "applicationCategory": "BusinessApplication",
  "offers": [
    {
      "@type": "Offer",
      "name": "[Plan Name]",
      "price": "[Price]",
      "priceCurrency": "USD"
    }
  ]
};

// Blog Posts
const articleSchema = {
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Title]",
  "author": { "@type": "Person", "name": "[Author]" },
  "datePublished": "[Date]",
  "image": "[Image URL]"
};

Gohar's Decision Framework

When planning sprints, use this to assign tasks: