Architecture Diagrams

// Need to understand overall architecture?
→ See Diagram 1: Overall System Architecture

// Building authentication?
→ See Diagram 2: Authentication Flow

// Working with APIs?
→ See Diagram 3: API & SDK Generation Pipeline

// Integrating analytics?
→ See Diagram 4: User Authentication with Analytics

// Building AI features?
→ See Diagram 5: AI Chatbot with Guardrails

// Implementing feature flags?
→ See Diagram 6: Feature Flag Rollout & Measurement

// Building notifications?
→ See Diagram 7: Real-time Notification System

// Tracing data flows?
→ See Diagram 8: Data Flow (Database to UI)

// Debugging errors?
→ See Diagram 9: Observability & Error Tracking

// Understanding deployments?
→ See Diagram 10: Build & Deployment Pipeline

graph LR
    A["📝 Your starting point"] --> B["🔧 Processing layer"]
    B --> C["💾 Data storage"]
    C --> D["📤 Output/Response"]

This PR implements authentication following the flow in
[Architecture Diagrams: Authentication Flow](/docs/guides/architecture-diagrams#2-authentication-flow)

The feature flag rollout follows
[Architecture Diagrams: Feature Flag Rollout](/docs/guides/architecture-diagrams#6-feature-flag-rollout--measurement)

graph TB
    subgraph UI["🎨 UI Stage (Client)"]
        Client["React Components<br/>Client Components<br/>Mantine + Tailwind"]
    end

    subgraph Server["🔧 Server Stage"]
        RSC["React Server<br/>Components"]
        Actions["Server Actions<br/>Route Handlers"]
    end

    subgraph Edge["⚡ Edge Stage"]
        Middleware["Middleware<br/>Edge Functions"]
    end

    subgraph Packages["📦 Packages Stage"]
        Auth["@repo/auth<br/>@repo/security"]
        Analytics["@repo/analytics<br/>@repo/observability"]
        AI["@repo/ai<br/>@repo/ai-oneapp"]
        Storage["@repo/storage<br/>@repo/email"]
        Utils["@repo/core-utils<br/>@repo/types"]
    end

    subgraph Data["💾 Data Stage"]
        DB["@repo/db-prisma<br/>Prisma ORM"]
        Redis["@repo/db-upstash-redis<br/>Cache & Queues"]
        Vector["@repo/db-upstash-vector<br/>Vector Embeddings"]
    end

    subgraph Infra["🚀 Infrastructure"]
        CI["GitHub Actions<br/>CI/CD"]
        Deploy["Vercel<br/>Deployment"]
    end

    Client -->|uses| UI
    Client -->|calls| Server
    Server -->|uses| Packages
    Edge -->|wraps| Server
    Packages -->|queries| Data
    CI -->|validates| Packages
    Deploy -->|deploys| Infra

    classDef uiStage fill:#6366f1
    classDef serverStage fill:#8b5cf6
    classDef edgeStage fill:#ec4899
    classDef packageStage fill:#f59e0b
    classDef dataStage fill:#10b981
    classDef infraStage fill:#6b7280

    class UI uiStage
    class Server serverStage
    class Edge edgeStage
    class Packages packageStage
    class Data dataStage
    class Infra infraStage

graph TB
    subgraph DB["💾 Database"]
        PrismaDB["Prisma Schema<br/>Tables & Relations"]
    end

    subgraph ORM["🔧 ORM Layer"]
        FindMany["findMany*Orm<br/>Query builder"]
        FindUnique["findUnique*Orm<br/>Get by ID"]
    end

    subgraph Server["🔧 Server Layer"]
        Action["Server Action<br/>or API Route"]
        Validate["Validate<br/>with Zod"]
        Transform["Transform Data<br/>for client"]
    end

    subgraph Client["🎨 Client Layer"]
        Hook["useQuery Hook<br/>or useSWR"]
        Cache["Cache Data<br/>React Query"]
        Component["React Component<br/>Render UI"]
    end

    PrismaDB -->|query| FindMany
    PrismaDB -->|by id| FindUnique

    FindMany -->|execute| Action
    FindUnique -->|execute| Action

    Action -->|schema| Validate
    Validate -->|success| Transform

    Transform -->|JSON| Hook
    Hook -->|cache| Cache
    Cache -->|render| Component

    classDef dbStage fill:#10b981,color:#fff
    classDef ormStage fill:#f59e0b,color:#000
    classDef serverStage fill:#8b5cf6,color:#fff
    classDef clientStage fill:#6366f1,color:#fff

    class DB dbStage
    class ORM ormStage
    class Server serverStage
    class Client clientStage

graph LR
    subgraph Dev["💻 Development"]
        Code["Commit Code"]
    end

    subgraph CI["🔍 CI Pipeline"]
        Lint["Lint<br/>ESLint"]
        Type["Type Check<br/>TypeScript"]
        Test["Test<br/>Vitest"]
        Coverage["Coverage<br/>Check"]
    end

    subgraph Quality["✅ Quality Gates"]
        Pass["All Checks<br/>Pass?"]
    end

    subgraph Build["🏗️ Build"]
        Next["Next.js Build<br/>Turbo"]
        Package["Package Apps<br/>ESM/CJS"]
    end

    subgraph Deploy["🚀 Deployment"]
        Staging["Deploy to<br/>Staging"]
        Preview["Preview URLs"]
        Prod["Deploy to<br/>Production"]
    end

    Code -->|push| Lint
    Lint -->|pass| Type
    Type -->|pass| Test
    Test -->|pass| Coverage
    Coverage -->|result| Pass

    Pass -->|✓ yes| Next
    Pass -->|✗ no| Code

    Next -->|success| Package
    Package -->|ready| Staging
    Staging -->|generate| Preview
    Preview -->|approved| Prod

    classDef devStage fill:#fbbf24,color:#000
    classDef ciStage fill:#ec4899,color:#fff
    classDef qualityStage fill:#8b5cf6,color:#fff
    classDef buildStage fill:#10b981,color:#fff
    classDef deployStage fill:#6366f1,color:#fff

    class Dev devStage
    class CI ciStage
    class Quality qualityStage
    class Build buildStage
    class Deploy deployStage

sequenceDiagram
    actor User
    participant Browser
    participant App as "Next.js App"
    participant Auth as "@repo/auth"
    participant DB as "Prisma"
    participant Session as "Session"

    User->>Browser: Navigate to /login
    Browser->>App: Request login page
    App->>Browser: Render login form

    User->>Browser: Enter credentials
    Browser->>App: POST /api/auth/signin
    App->>Auth: verifyCredentials()
    Auth->>DB: Query user
    DB->>Auth: User found

    alt Credentials valid
        Auth->>Session: Create session
        Session->>Browser: Set secure cookie
        Browser->>App: Redirect to /dashboard
        App->>Auth: getSession()
        Auth->>Browser: Authenticated dashboard
    else Invalid credentials
        Auth->>Browser: 401 Unauthorized
        Browser->>User: Show error
    end

graph TB
    subgraph Client["🎨 Client"]
        Login["Login Form"]
        Track["Track Event"]
    end

    subgraph Auth["🔐 Authentication"]
        Verify["Verify Credentials"]
        CreateSession["Create Session"]
        SetCookie["Set Auth Cookie"]
    end

    subgraph Analytics["📊 Analytics"]
        Identify["Identify User"]
        Emit["Emit Event"]
    end

    subgraph DB["💾 Database"]
        UserTable["users table"]
        SessionTable["sessions table"]
    end

    Login -->|POST /api/auth/signin| Verify
    Verify -->|query| UserTable
    UserTable -->|user data| CreateSession
    CreateSession -->|write| SessionTable
    SessionTable -->|✓ success| SetCookie
    SetCookie -->|auth cookie| Client
    Client -->|analytics.identify()| Identify
    Identify -->|set context| Emit
    Emit -->|send to PostHog| Analytics

    classDef clientStage fill:#6366f1,color:#fff
    classDef authStage fill:#8b5cf6,color:#fff
    classDef analyticsStage fill:#ec4899,color:#fff
    classDef dataStage fill:#10b981,color:#fff

    class Client clientStage
    class Auth authStage
    class Analytics analyticsStage
    class DB dataStage

graph LR
    A["📝 Prisma Schema<br/>@repo/oneapp-shared<br/>prisma/schema.prisma"]

    B["🔧 Prisma Generate<br/>prisma generate<br/>--schema=prisma"]

    C["📦 ORM Layer<br/>@repo/oneapp-shared/orm<br/>Generated CRUD functions"]

    D["🛣️ API Routes<br/>@repo/oneapp-api<br/>/api/v1/{schema}/{model}"]

    E["📋 OpenAPI Spec<br/>prisma-openapi<br/>openapi.json"]

    F["🎯 Path Generator<br/>Scans API routes<br/>Generates paths"]

    G["🔗 Merge OpenAPI<br/>Combines schemas + paths<br/>openapi-complete.json"]

    H["🎁 HeyAPI Generation<br/>openapi-ts<br/>Generates TypeScript"]

    I["📚 SDK<br/>@repo/oneapp-sdk<br/>263 typed functions"]

    J["💻 Client Code<br/>React Components<br/>Server Actions"]

    A -->|generate| B
    B -->|creates| C
    C -->|powers| D
    B -->|generates| E
    D -->|scanned by| F
    F -->|feeds| G
    E -->|merged with| G
    G -->|input to| H
    H -->|generates| I
    I -->|consumed by| J

    classDef source fill:#fbbf24
    classDef gen fill:#60a5fa
    classDef output fill:#34d399

    class A source
    class B,F,H gen
    class I,J output

graph TB
    subgraph Input["📝 Input & Validation"]
        UserMsg["User Message"]
        RateCheck["Rate Limit Check"]
        SafetyCheck["Safety Guardrails<br/>Banned Topics"]
    end

    subgraph Processing["🤖 AI Processing"]
        AIGen["Generate Response<br/>@repo/ai"]
        Trace["Trace Metrics<br/>@repo/observability"]
        Track["Track Usage<br/>@repo/analytics"]
    end

    subgraph Storage["💾 Data"]
        SaveMsg["Save Message<br/>@repo/db-prisma"]
        SaveCost["Save Cost<br/>Tokens + USD"]
    end

    subgraph Output["📤 Output"]
        Stream["Stream Response"]
        Display["Display Chat"]
    end

    UserMsg -->|check| RateCheck
    RateCheck -->|check| SafetyCheck
    SafetyCheck -->|✓ pass| AIGen
    AIGen -->|metrics| Trace
    Trace -->|tokens/latency| Track
    Track -->|log event| SaveMsg
    SaveMsg -->|log cost| SaveCost
    SaveCost -->|return response| Stream
    Stream -->|render| Display

    SafetyCheck -->|❌ fail| Display
    RateCheck -->|❌ blocked| Display

    classDef inputStage fill:#f59e0b,color:#000
    classDef processingStage fill:#8b5cf6,color:#fff
    classDef storageStage fill:#10b981,color:#fff
    classDef outputStage fill:#6366f1,color:#fff

    class Input inputStage
    class Processing processingStage
    class Storage storageStage
    class Output outputStage

graph LR
    subgraph Planning["📋 Planning"]
        Plan["Define Feature<br/>Success Metrics"]
    end

    subgraph Rollout["🚀 Rollout"]
        Flag["Set Feature Flag<br/>PostHog"]
        Track["Track Exposure<br/>@repo/analytics"]
        Percent["Gradual %<br/>0% → 100%"]
    end

    subgraph Measurement["📊 Measurement"]
        Exposure["Exposure Data<br/>Who saw it?"]
        Behavior["User Behavior<br/>What did they do?"]
        Impact["Impact Analysis<br/>Did it help?"]
    end

    subgraph Decision["✅ Decision"]
        Accept["Accept & Rollout<br/>100%"]
        Reject["Reject & Rollback<br/>0%"]
        Iterate["Iterate & Refine<br/>Adjust feature"]
    end

    Plan -->|configure| Flag
    Flag -->|emit events| Track
    Track -->|gradual increase| Percent
    Percent -->|collect data| Exposure
    Exposure -->|analyze behavior| Behavior
    Behavior -->|calculate impact| Impact

    Impact -->|positive result| Accept
    Impact -->|negative result| Reject
    Impact -->|mixed results| Iterate

    classDef planning fill:#fbbf24,color:#000
    classDef rollout fill:#8b5cf6,color:#fff
    classDef measurement fill:#10b981,color:#fff
    classDef decision fill:#6366f1,color:#fff

    class Planning planning
    class Rollout rollout
    class Measurement measurement
    class Decision decision

graph TB
    subgraph Event["⚡ Event Trigger"]
        Action["User Action<br/>e.g., Order placed"]
    end

    subgraph Generate["📝 Generate"]
        Create["Create Notification<br/>@repo/db-prisma"]
        Template["Select Template<br/>@repo/email"]
    end

    subgraph Deliver["📤 Delivery"]
        Email["Send Email<br/>via Resend"]
        WebSocket["Send WebSocket<br/>Real-time"]
    end

    subgraph Track["📊 Track"]
        Sent["Mark Sent<br/>@repo/analytics"]
        Opened["Track Open"]
        Clicked["Track Click"]
        Dismissed["Track Dismiss"]
    end

    subgraph Monitor["🔍 Monitor"]
        Logs["Log Delivery<br/>@repo/observability"]
        Metrics["Measure Rate<br/>Opens/Clicks"]
    end

    Action -->|trigger| Create
    Create -->|render| Template
    Template -->|send| Email
    Template -->|emit| WebSocket
    Email -->|log event| Sent
    WebSocket -->|log event| Sent
    Sent -->|user action| Opened
    Opened -->|user action| Clicked
    Opened -->|user action| Dismissed

    Clicked -->|record| Logs
    Dismissed -->|record| Logs
    Logs -->|aggregate| Metrics

    classDef eventStage fill:#f59e0b,color:#000
    classDef generateStage fill:#8b5cf6,color:#fff
    classDef deliverStage fill:#ec4899,color:#fff
    classDef trackStage fill:#10b981,color:#fff
    classDef monitorStage fill:#6366f1,color:#fff

    class Event eventStage
    class Generate generateStage
    class Deliver deliverStage
    class Track trackStage
    class Monitor monitorStage

graph TB
    subgraph Sources["🔍 Event Sources"]
        Errors["Errors<br/>try/catch"]
        Logs["Log Messages<br/>logInfo/logError"]
        Metrics["Metrics<br/>Performance data"]
        WebVitals["Web Vitals<br/>LCP, FID, CLS"]
    end

    subgraph Collection["📦 Collection"]
        Client["Client Collector<br/>Browser"]
        Server["Server Collector<br/>Node.js"]
        Edge["Edge Collector<br/>Middleware"]
    end

    subgraph Processing["⚙️ Processing"]
        Sentry["Sentry<br/>Error tracking"]
        BetterStack["BetterStack<br/>Log aggregation"]
        PostHog["PostHog<br/>Analytics"]
    end

    subgraph Visualization["📊 Visualization"]
        Dashboard["Dashboards"]
        Alerts["Alerts"]
        Reports["Reports"]
    end

    Errors -->|captured| Client
    Logs -->|captured| Server
    Logs -->|captured| Edge
    Metrics -->|captured| Server
    WebVitals -->|captured| Client

    Client -->|batch send| Sentry
    Server -->|send| BetterStack
    Edge -->|send| Sentry
    Server -->|emit| PostHog

    Sentry -->|aggregate| Dashboard
    BetterStack -->|aggregate| Dashboard
    PostHog -->|aggregate| Dashboard

    Dashboard -->|trigger| Alerts
    Dashboard -->|generate| Reports

    classDef sourcesStage fill:#f59e0b,color:#000
    classDef collectionStage fill:#8b5cf6,color:#fff
    classDef processingStage fill:#10b981,color:#fff
    classDef visualizationStage fill:#6366f1,color:#fff

    class Sources sourcesStage
    class Collection collectionStage
    class Processing processingStage
    class Visualization visualizationStage

graph TB
    subgraph UI["🎨 UI Layer"]
        Client["Client Components<br/>React hooks<br/>Browser APIs"]
    end

    subgraph Server["🔧 Server Layer"]
        RSC["Server Components<br/>Database access<br/>Node.js APIs"]
    end

    subgraph Packages["📦 Packages"]
        Universal["Universal<br/>No React/Next"]
    end

    UI -->|ALLOWED| Packages
    Server -->|ALLOWED| Packages
    Packages -->|FORBIDDEN| UI
    Packages -->|FORBIDDEN| Server

    UI -->|FORBIDDEN| Server

    classDef allowed fill:#10b981,color:#fff
    classDef forbidden fill:#ef4444,color:#fff
    classDef package fill:#f59e0b,color:#000

    class allowed
    class forbidden
    class package

graph TB
    subgraph Try["🔧 Try Block"]
        Code["Business Logic"]
    end

    subgraph Catch["❌ Catch Block"]
        Log["Log Error<br/>@repo/observability"]
        Track["Track Event<br/>@repo/analytics"]
        Respond["Return Error<br/>Response"]
    end

    Code -->|error| Log
    Log -->|add context| Track
    Track -->|format| Respond
    Respond -->|to client| User["User Sees<br/>Safe Message"]

    classDef tryStage fill:#10b981,color:#fff
    classDef catchStage fill:#ef4444,color:#fff

    class Try tryStage
    class Catch catchStage