# areid987/quality-neighbor-monorepo architecture

> Architecture diagram of the GitHub repository areid987/quality-neighbor-monorepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/areid987/quality-neighbor-monorepo
- Repository: https://github.com/areid987/quality-neighbor-monorepo

## Overview

##### Project Type and Purpose
- This is a full-stack monorepo (Turborepo) housing multiple Next.js apps (“qn-dashboard”, “qn-platform”, “qn-business”) and a backend API (“qn-api”), plus shared packages (UI, types, auth, database, config).
- Purpose:
- qn-dashboard: internal team operations
- qn-platform: resident-facing web platform
- qn-business: business owner portal
- qn-api: shared backend services (auth, data, email, file storage)

##### High-Level File Structure
- apps/
- qn-dashboard, qn-platform, qn-business, qn-api
- packages/
- @qn/ui, @qn/types, @qn/auth, @qn/database, @qn/config
- Quality-Neighbor-Docs/ (detailed docs)
- supabase/ (local Supabase config & migrations)
- scripts/ (deploy/test scripts)
- root config: pnpm-workspace.yaml, turbo.json, tsconfig.json

##### Key Architectural Insights from README
- Shared UI components (Radix+Tailwind) and TS types enforce consistency.
- Backend: Node.js + Express planned, PostgreSQL (via Supabase) + JWT RBAC, Stripe Identity, SendGrid/Mailgun.
- Frontend apps use Next.js 13 App Router, React, TS, Tailwind CSS.
- CI/CD via GitHub Actions; deployments to Vercel/Netlify (frontend) and AWS/GCP (API, DB).

a. Main Components
- Developer Environment & Monorepo (Turborepo + PNPM)
- Shared Packages Layer (@qn/ui, @qn/types, @qn/auth, @qn/database, @qn/config)
- Frontend Apps: qn-dashboard, qn-platform, qn-business (Next.js apps)
- Backend API: qn-api (Express/Next.js API routes)
- Database: PostgreSQL (hosted/Supabase)
- External Services: Stripe Identity, SendGrid/Mailgun, File Storage (S3/GCS)
b. Relationships & Interactions
- Frontend apps import shared packages at build time.
- Frontends make HTTP/GraphQL calls to the qn-api.
- qn-api uses @qn/database for migrations/client, @qn/auth for JWT/RBAC.
- qn-api reads/writes to PostgreSQL (Supabase), invokes external services (Stripe, Email, Storage).
- CI/CD pipeline triggers builds of apps and packages; deployment scripts push to hosting.
c. Architectural Patterns & Principles
- Monorepo with Turborepo: code sharing and atomic changes.
- Modular packages: single responsibility, shareable code.
- “Separation of Concerns”: distinct frontends vs backend services.
- Scalable micro-service style: each app can be deployed independently.
- App Router pattern in Next.js for server-side logic in frontend.
d. Technologies & Frameworks
- Frontend: Next.js 13, React, TypeScript, Tailwind CSS, Radix UI
- Backend: Node.js, Express.js (or Next.js API routes), JWT, Role-based access
- Database: PostgreSQL (Supabase), migrations via @qn/database
- Auth: JWT, Stripe Identity via @qn/auth
- CI/CD: GitHub Actions, Turborepo, PNPM workspaces
- Hosting: Vercel/Netlify (frontend), AWS/GCP (API & DB), S3/GCS for assets

## Diagram (Mermaid)

```mermaid
graph TB
    %% Monorepo & Dev Environment
    subgraph "Monorepo & Dev Environment"
        direction TB
        PNPM["pnpm-workspace.yaml"]:::monorepo
        TURBO["turbo.json"]:::monorepo
        TSCONFIG["tsconfig.json (root)"]:::monorepo
    end

    %% Shared Packages Layer
    subgraph "Shared Packages" 
        direction TB
        AUTH["@qn/auth"]:::shared
        CONFIG["@qn/config"]:::shared
        DATABASE_PKG["@qn/database"]:::shared
        TYPES["@qn/types"]:::shared
        UI_PKG["@qn/ui"]:::shared
    end

    %% Frontend Applications
    subgraph "Frontend Applications"
        direction TB
        subgraph "qn-dashboard"
            direction TB
            QD_DIR["Directory: apps/qn-dashboard"]:::frontend
            QD_PAGE["App Entry: page.tsx"]:::frontend
            QD_LAYOUT["Layout: layout.tsx"]:::frontend
            QD_GLOBALS["Global Styles: globals.css"]:::frontend
            QD_UI["UI Components: components/ui/"]:::frontend
            QD_AUTH_COMP["Auth Form: login-form.tsx"]:::frontend
            QD_API_ROUTE["API Route: [...auth0].ts"]:::frontend
            QD_DB_UTIL["DB Utils: lib/database.ts"]:::frontend
        end
        subgraph "qn-platform"
            direction TB
            QP_DIR["Directory: apps/qn-platform"]:::frontend
            QP_PAGE["App Entry: src/app/page.tsx"]:::frontend
            QP_LAYOUT["Layout: src/app/layout.tsx"]:::frontend
            QP_GLOBALS["Globals: src/app/globals.css"]:::frontend
            QP_DASHBOARD["Dashboard: src/app/dashboard/page.tsx"]:::frontend
            QP_UI["UI Components: src/components/ui/"]:::frontend
            QP_SIGNIN["Auth: SignInForm.tsx"]:::frontend
            QP_SIGNUP["Auth: SignUpForm.tsx"]:::frontend
            QP_SUPA_CFG["Supabase Config: supabase/config.toml"]:::frontend
            QP_SUPA_MIG["Migrations: supabase/migrations/"]:::frontend
        end
        QB["qn-business"]:::frontend
    end

    %% Backend API
    QN_API["qn-api (Express/Next.js API)"]:::backend

    %% Database
    POSTGRES["PostgreSQL (Supabase)"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        STRIPE["Stripe Identity"]:::external
        EMAIL["SendGrid/Mailgun"]:::external
        STORAGE["S3/GCS Storage"]:::external
    end

    %% CI/CD & Scripts
    subgraph "CI/CD & Scripts"
        direction TB
        GH_ACTIONS["GitHub Actions"]:::ci
        TURBO_BUILD["Turborepo Build"]:::ci
        DEPLOY_SCRIPTS["Deploy Scripts"]:::ci
        SUPA_LOCAL["Supabase Local: supabase/"]:::ci
    end

    %% Connections
    PNPM -->|workspace| AUTH
    PNPM -->|workspace| CONFIG
    PNPM -->|workspace| DATABASE_PKG
    PNPM -->|workspace| TYPES
    PNPM -->|workspace| UI_PKG

    TURBO --> AUTH
    TURBO --> CONFIG
    TURBO --> DATABASE_PKG
    TURBO --> TYPES
    TURBO --> UI_PKG

    AUTH --> QD_DIR
    CONFIG --> QD_DIR
    DATABASE_PKG --> QD_DIR
    TYPES --> QD_DIR
    UI_PKG --> QD_DIR

    AUTH --> QP_DIR
    CONFIG --> QP_DIR
    DATABASE_PKG --> QP_DIR
    TYPES --> QP_DIR
    UI_PKG --> QP_DIR

    AUTH --> QB
    CONFIG --> QB
    DATABASE_PKG --> QB
    TYPES --> QB
    UI_PKG --> QB

    QD_DIR --> QN_API
    QP_DIR --> QN_API
    QB --> QN_API

    QN_API --> POSTGRES
    QN_API --> STRIPE
    QN_API --> EMAIL
    QN_API --> STORAGE

    GH_ACTIONS --> TURBO_BUILD
    TURBO_BUILD --> DEPLOY_SCRIPTS
    DEPLOY_SCRIPTS --> QD_DIR
    DEPLOY_SCRIPTS --> QP_DIR
    DEPLOY_SCRIPTS --> QB
    DEPLOY_SCRIPTS --> QN_API
    GH_ACTIONS --> SUPA_LOCAL

    %% Click Events
    click PNPM "https://github.com/areid987/quality-neighbor-monorepo/blob/main/pnpm-workspace.yaml"
    click TURBO "https://github.com/areid987/quality-neighbor-monorepo/blob/main/turbo.json"
    click TSCONFIG "https://github.com/areid987/quality-neighbor-monorepo/blob/main/tsconfig.json"
    click AUTH "https://github.com/areid987/quality-neighbor-monorepo/tree/main/packages/auth"
    click CONFIG "https://github.com/areid987/quality-neighbor-monorepo/tree/main/packages/config"
    click DATABASE_PKG "https://github.com/areid987/quality-neighbor-monorepo/tree/main/packages/database"
    click TYPES "https://github.com/areid987/quality-neighbor-monorepo/tree/main/packages/types"
    click UI_PKG "https://github.com/areid987/quality-neighbor-monorepo/tree/main/packages/ui"
    click QD_DIR "https://github.com/areid987/quality-neighbor-monorepo/tree/main/apps/qn-dashboard"
    click QD_PAGE "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/app/page.tsx"
    click QD_LAYOUT "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/app/layout.tsx"
    click QD_GLOBALS "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/app/globals.css"
    click QD_UI "https://github.com/areid987/quality-neighbor-monorepo/tree/main/apps/qn-dashboard/components/ui/"
    click QD_AUTH_COMP "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/components/auth/login-form.tsx"
    click QD_API_ROUTE "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/pages/api/auth/[...auth0].ts"
    click QD_DB_UTIL "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-dashboard/lib/database.ts"
    click QP_DIR "https://github.com/areid987/quality-neighbor-monorepo/tree/main/apps/qn-platform"
    click QP_PAGE "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/app/page.tsx"
    click QP_LAYOUT "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/app/layout.tsx"
    click QP_GLOBALS "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/app/globals.css"
    click QP_DASHBOARD "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/app/dashboard/page.tsx"
    click QP_UI "https://github.com/areid987/quality-neighbor-monorepo/tree/main/apps/qn-platform/src/components/ui/"
    click QP_SIGNIN "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/components/auth/SignInForm.tsx"
    click QP_SIGNUP "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/src/components/auth/SignUpForm.tsx"
    click QP_SUPA_CFG "https://github.com/areid987/quality-neighbor-monorepo/blob/main/apps/qn-platform/supabase/config.toml"
    click QP_SUPA_MIG "https://github.com/areid987/quality-neighbor-monorepo/tree/main/apps/qn-platform/supabase/migrations/"
    click SUPA_LOCAL "https://github.com/areid987/quality-neighbor-monorepo/tree/main/supabase/"

    %% Styles
    classDef monorepo fill:#dddddd,stroke:#999,stroke-width:1px
    classDef shared fill:#ffd27f,stroke:#e69500,stroke-width:1px
    classDef frontend fill:#a0c4ff,stroke:#1f78b4,stroke-width:1px
    classDef backend fill:#b7e4c7,stroke:#2d6a4f,stroke-width:1px
    classDef database fill:#cdb4db,stroke:#6a4c93,stroke-width:1px
    classDef external fill:#ffadad,stroke:#d00000,stroke-width:1px
    classDef ci fill:#caffbf,stroke:#2e7d32,stroke-width:1px
```
