# servicios-kdv-2025/sisescolar-25 architecture

> Architecture diagram of the GitHub repository servicios-kdv-2025/sisescolar-25, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/servicios-kdv-2025/sisescolar-25
- Repository: https://github.com/servicios-kdv-2025/sisescolar-25

## Overview

##### Project type and purpose
- This is a full-stack monorepo managed with Turborepo.
- It contains three Next.js applications under `/apps`:
- **admin** – a Next.js frontend for administrators
- **payload** – a Next.js site integrated with Payload CMS for public content and headless CMS capabilities
- **system** – a Next.js multi-tenant “dashboard” app for schools, teachers, students
- Shared packages under `/packages` provide:
- UI components (`ui`)
- Convex backend functions & real-time DB (`convex`)
- ESLint and TypeScript config presets

##### High-level architectural components
- **Monorepo root**
- Turborepo orchestrates builds/dev tasks, remote caching via Vercel
- Shared configs: `turbo.json`, `pnpm-workspace.yaml`
- **Apps layer (/apps)**
- admin (uses Convex client + Payload API)
- payload (Next.js + Payload CMS + Convex client + Stripe endpoints)
- system (Next.js multi-tenant dashboard + Convex client)
- **Backend services**
- **Convex** – serverless functions and real-time DB; defined under `/packages/convex/convex` and used by all apps via generated API client
- **Payload CMS** – Node.js-based headless CMS for content storage; uses its own local/production database (e.g., `prueba.db` in development)
- **Stripe** – payment session and webhook endpoints implemented in the payload app
- **Shared libraries (/packages)**
- `ui` – shared React component library consumed by all Next.js apps
- `eslint-config`, `typescript-config`, `zod-config` – linting, typing, validation presets

##### Relationships and data flows
- **Next.js frontends** → call → **Convex client** → invokes → **Convex serverless functions** → operate on → **Convex DB**
- **payload app** → calls → **Payload CMS internal API** for content management → persists in its own DB
- **payload app** → integrates → **Stripe API** (via API routes) for payment sessions & webhooks
- **admin** & **system** apps → share → **ui** library and → call → **Convex** for application data
- All apps share code and configs via Turborepo caching and workspace package resolution

##### Key architectural patterns & design principles
- **Monorepo with Turborepo** for unified task running, caching, dependency graph awareness
- **Micro-frontend style**: three separate Next.js apps with their own concerns but shared libraries
- **Serverless backend**: Convex functions as business logic layer, abstracting database operations
- **Headless CMS**: Payload for managing content via a code-driven schema in `/apps/payload/src/collections`
- **Multi-tenant routing**: `apps/system` uses dynamic `[subdomain]` routing for per-school dashboards

##### Detail level
- Major component rather than individual pages/files
- Shared `ui` package linking into all three frontends
- Multi-tenant dynamic routing in the system app by labeling `[subdomain]`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Next.js Frontends"
        direction TB
        AdminApp["admin app"]:::frontend
        PayloadApp["payload app"]:::frontend
        SystemApp["system app\n[multi-tenant]"]:::frontend
    end

    %% Shared Packages Layer
    subgraph "Shared Packages" 
        direction TB
        UI["ui library"]:::shared
        ESLint["eslint-config"]:::shared
        TSConfig["typescript-config"]:::shared
        ZodConfig["zod-config"]:::shared
        ConvexClient["convex client\n(api)_generated"]:::shared
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        direction TB
        ConvexFunctions["Convex functions"]:::backendService
        ConvexDB["Convex DB"]:::db
        PayloadCMS["Payload CMS"]:::backendService
        PayloadDB["Payload DB"]:::db
        StripeService["Stripe API"]:::external
    end

    %% Monorepo Config
    MonorepoRootConfig["Monorepo Root\n(Turborepo)"]:::infra

    %% Connections: Frontends to Shared
    AdminApp -->|"uses UI"| UI
    AdminApp -->|"calls ConvexClient"| ConvexClient

    PayloadApp -->|"uses UI"| UI
    PayloadApp -->|"calls ConvexClient"| ConvexClient
    PayloadApp -->|"HTTP API"| PayloadCMS
    PayloadApp -->|"HTTP API"| StripeService

    SystemApp -->|"uses UI"| UI
    SystemApp -->|"calls ConvexClient"| ConvexClient

    %% Shared to Backend
    ConvexClient -->|"invokes"| ConvexFunctions
    ConvexFunctions -->|"operates on"| ConvexDB
    PayloadCMS -->|"persists in"| PayloadDB

    %% Monorepo root to Shared
    MonorepoRootConfig --> UI
    MonorepoRootConfig --> ESLint
    MonorepoRootConfig --> TSConfig
    MonorepoRootConfig --> ZodConfig

    %% Click Events
    click MonorepoRootConfig "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/turbo.json"
    click AdminApp "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/admin"
    click AdminApp "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/admin/next.config.js"
    click AdminPage "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/admin/app/page.tsx"
    click AdminLayout "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/admin/app/layout.tsx"
    click AdminConvexWrapper "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/admin/components/ConvexProviderWrapper.tsx"
    click PayloadApp "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/payload"
    click PayloadConfig "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/payload/src/payload.config.ts"
    click PayloadCollections "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/payload/src/collections"
    click StripeCheckout "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/payload/src/app/api/checkout/route.ts"
    click ConvexPayloadGenerated "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/payload/convex/_generated"
    click PayloadDB "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/payload/prueba.db"
    click SystemApp "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/system"
    click SystemSubdomain "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/apps/system/app/[subdomain]"
    click SystemSidebar "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/apps/system/components/AppSidebarWithData.tsx"
    click ConvexBackend "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/packages/convex/convex"
    click UIShared "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/packages/ui"
    click ESLintConfig "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/packages/eslint-config"
    click TSConfigShared "https://github.com/servicios-kdv-2025/sisescolar-25/tree/main/packages/typescript-config"
    click ZodConfig "https://github.com/servicios-kdv-2025/sisescolar-25/blob/main/packages/zod-config/index.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef shared fill:#e6ccff,stroke:#9933ff,stroke-width:2px
    classDef backendService fill:#d5f5e3,stroke:#28a745,stroke-width:2px,stroke-dasharray: 5 5
    classDef db fill:#d4efdf,stroke:#27ae60,stroke-width:2px
    classDef external fill:#fdebd0,stroke:#f39c12,stroke-width:2px
    classDef infra fill:#f0f0f0,stroke:#888888,stroke-width:2px,stroke-dasharray: 2 2
```
