# felipefl200/saas-turborepo-next architecture

> Architecture diagram of the GitHub repository felipefl200/saas-turborepo-next, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/felipefl200/saas-turborepo-next
- Repository: https://github.com/felipefl200/saas-turborepo-next

## Overview

##### Project Type and Purpose
- This is a **monorepo SaaS application** managed by Turborepo.
- **Frontend**: Next.js (React) web application (inferred at `apps/web`).
- **Backend**: Fastify-based REST API at `apps/api`.
- **Shared Packages**: RBAC/auth logic (`packages/auth`), environment utilities (`packages/env`).
- **Database**: Prisma ORM backed by a relational database (e.g., Postgres).
- **Auth**: Custom RBAC multi-tenant system, GitHub OAuth, password flows.

##### File Structure and Key Layers
- **Monorepo Orchestration** (`turbo.json`, root `package.json`, `docker-compose.yml`): central build/run.
- **Apps/**
- `apps/api/`: Fastify server
– HTTP layer: `src/http/server.ts`, routers in `routes/*`, middleware in `middlewares/*`, error handlers.
– Business/core: utils in `src/utils/*`, Prisma client in `src/lib/prisma.ts`.
– Data model & migrations: `prisma/schema.prisma`, seed scripts.
- `apps/web/` (not shown but documented): Next.js UI, pages/components, UI-level RBAC.
- **Packages/** (shared libraries)
- `packages/auth/`: RBAC rules, permission subjects, models for user/org/project, middleware hooks.
- `packages/env/`: Environment variable loader, type definitions.
- **Config/**: ESLint, Prettier, TypeScript base and overrides.

##### Main Components
A. **User & Client**
– Browser (React/Next.js SPA)
– HTTP (HTTPS)
B. **Frontend** (`apps/web`)
– Next.js Server-Side Rendering & API Routes (if any)
– UI Components & RBAC Guards (from `packages/auth`)
C. **API Gateway / Backend** (`apps/api`)
– Fastify HTTP Server
– Authentication & Authorization Middleware
– Route Handlers → call business logic/utilities
D. **Shared Business Logic**
– `packages/auth` RBAC engine
– `packages/env` configuration
E. **Data Layer**
– Prisma Client (auto-generated code in `apps/api/src/generated/prisma`)
– Relational Database (Postgres/MySQL)
F. **External Services**
– GitHub OAuth endpoint
– Email/SMS provider for password recovery
G. **Infrastructure & DevOps**
– Turborepo build pipeline
– Docker Compose for local dev
– CI/CD (e.g., GitHub Actions – inferred)

##### Relationships & Data Flows
- **Client → Frontend**: User requests page or API route → Next.js
- **Frontend → Backend**: REST calls over HTTPS to Fastify
- **Backend**:
- Auth middleware checks JWT/session → resolves user identity & roles via `packages/auth`.
- Route handlers invoke Prisma client to query/update database.
- **Database**: Prisma translates queries → SQL → Database
- **External OAuth**: Backend ↔ GitHub for social login
- **Dev Tools**: Turborepo orchestrates builds/test across packages/apps; Docker Compose spins up API + DB

##### Architectural Patterns & Principles
- **Monorepo with Code Sharing**: Turborepo sharable packages vs. siloed apps
- **Layered Architecture**: Presentation (Next.js), API (Fastify), Business (packages/auth), Data (Prisma)
- **RBAC Pattern**: Centralized permission engine in `packages/auth` plus middleware enforcement
- **Modularization**: HTTP routes separated by domain (`auth`, `orgs`, `projects`)
- **Infrastructure as Code**: Docker Compose, environment config in code

##### Final Checklist
- All major modules: Web, API, Auth Package, Env Package, DB, External Services.
- Labels for directories, libraries, protocols.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Subgraphs
  subgraph "Monorepo Root"
    subgraph "Infra"
      Turbo["turborepo (turbo.json)"]:::infra
      RootPkg["root package.json"]:::infra
      Docker["docker-compose.yml"]:::infra
    end
    subgraph "Apps"
      subgraph "Frontend (Next.js) (apps/web)"
        Browser["Browser (React/Next.js SPA)"]:::frontend
        NextServer["Next.js Server"]:::frontend
      end
      subgraph "Backend API (Fastify) (apps/api)"
        FastifyServer["Fastify HTTP Server"]:::backend
        AuthMiddleware["Authentication & Authorization Middleware"]:::backend
        Routes["HTTP Routes (auth/orgs/projects)"]:::backend
        ErrorHandler["Error Handler"]:::backend
        PrismaLib["Prisma Client Lib"]:::backend
        PrismaSchema["Prisma Schema (schema.prisma)"]:::data
        PrismaSeed["Seed Scripts"]:::data
        PrismaGenerated["Prisma Generated Client"]:::data
      end
    end
    subgraph "Packages"
      AuthPkg["Auth Package (RBAC)"]:::shared
      EnvPkg["Env Package"]:::shared
    end
  end

  %% External & Data
  DB["Relational Database"]:::data
  GitHub["GitHub OAuth Service"]:::external
  Email["Email/SMS Provider"]:::external
  CI["CI/CD (GitHub Actions)"]:::infra

  %% Flows
  Browser -->|"HTTPS Request"| NextServer
  NextServer -->|"REST API Calls"| FastifyServer
  NextServer -->|"Uses Auth Guards"| AuthPkg
  NextServer -->|"Loads Config"| EnvPkg

  FastifyServer --> Routes
  FastifyServer --> AuthMiddleware
  FastifyServer --> ErrorHandler
  FastifyServer --> EnvPkg
  FastifyServer --> GitHub
  FastifyServer --> Email

  AuthMiddleware -->|"RBAC Checks"| AuthPkg
  Routes --> PrismaLib
  PrismaLib --> PrismaGenerated
  PrismaGenerated -->|"SQL Queries"| DB

  %% Infra connections
  Docker --> FastifyServer
  Docker --> DB
  Turbo -.-> Apps
  Turbo -.-> Packages
  CI -.-> Turbo

  %% Click Events
  click Turbo "https://github.com/felipefl200/saas-turborepo-next/blob/main/turbo.json"
  click RootPkg "https://github.com/felipefl200/saas-turborepo-next/blob/main/package.json"
  click Docker "https://github.com/felipefl200/saas-turborepo-next/blob/main/docker-compose.yml"
  click FastifyServer "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/src/http/server.ts"
  click Routes "https://github.com/felipefl200/saas-turborepo-next/tree/main/apps/api/src/http/routes/"
  click AuthMiddleware "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/src/http/middlewares/auth.ts"
  click ErrorHandler "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/src/error-handler.ts"
  click PrismaLib "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/src/lib/prisma.ts"
  click PrismaSchema "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/prisma/schema.prisma"
  click PrismaSeed "https://github.com/felipefl200/saas-turborepo-next/blob/main/apps/api/prisma/seed.ts"
  click PrismaGenerated "https://github.com/felipefl200/saas-turborepo-next/tree/main/apps/api/src/generated/prisma/"
  click AuthPkg "https://github.com/felipefl200/saas-turborepo-next/blob/main/packages/auth/src/index.ts"
  click EnvPkg "https://github.com/felipefl200/saas-turborepo-next/blob/main/packages/env/index.ts"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
  classDef shared fill:#e2e3e5,stroke:#333,stroke-width:1px
  classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
  classDef external fill:#f5c6cb,stroke:#333,stroke-width:1px
  classDef infra fill:#d1ecf1,stroke:#333,stroke-width:1px
```
