# madrym/parakletos architecture

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

- Interactive diagram: https://gitdiagram.com/madrym/parakletos
- Repository: https://github.com/madrym/parakletos

## Overview

##### Project Type & Purpose
- This is a full-stack web application built with Next.js (App Router) on the frontend and Convex for backend functions & database.
- Purpose: fetch/display Bible passages, allow users to sign in/up, take and organize notes, annotate Bible verses, and run background cleanup crons.

##### Top-Level Components
a. Frontend (Next.js App)
- UI Pages and Layouts (`src/app/...`, `src/components/...`)
- Client-side state/context (`src/context/UserContext.tsx`)
- Styling: Tailwind CSS (`src/app/globals.css`, `tailwind.config.ts`)
- Data layer: local NIV.json store (`src/data/NIV.json`) & OpenAPI spec (`openapi/api.bible.openapi3.json`)
b. API Layer (Next.js Route Handler)
- `/api/getPassage` (`src/app/api/getPassage/route.ts`)
c. Backend Functions & Database (Convex)
- Convex server functions (`convex/*.ts`, `convex/*.js`) for queries/mutations: notes, noteSections, annotations, users
- Convex schema & generated client/server bindings (`convex/schema.ts`, `convex/_generated/*.js/.d.ts`)
- Cron jobs (cleanupNotes.ts, crons.js)
- Auth config (`convex/auth.config.ts`)
d. External Services
- Optional remote Bible API (spec’d in `openapi/api.bible.json`)
e. Deployment & CI/CD
- Hosting: Vercel
- GitHub Actions workflows (`.github/workflows/*.yaml`)

##### Interactions & Data Flows
- Browser → Next.js (SSR/SSG) on page load, React hydration
- React components ↔ Next.js route `getPassage` (HTTP) → reads local NIV.json or proxies to external Bible API
- React components ↔ Convex Client SDK (JS) → Convex Serverless functions → Convex Database
- Convex Cron scheduler → cleanupNotes function on regular intervals
- User auth flows: sign-in/sign-up via Convex Auth integration
- CI/CD: on push → GitHub Actions → deploy to Vercel preview/prod

##### Architectural Patterns & Principles
- Separation of concerns:
- UI layer (components & pages)
- API layer (Next.js route handlers)
- Business logic & data (Convex functions + DB)
- Serverless functions for backend logic (both Next.js and Convex)
- App Router pattern in Next.js for page routing and layouts
- Domain-driven folder structure (notes, users, annotations)
- Infrastructure as code: Convex schema + OpenAPI specs

##### Final Checklist
- Call out key technologies: Next.js, React, Tailwind CSS, Convex, OpenAPI, Vercel, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Browser"
        Browser["User Browser"]:::external
    end

    subgraph "Next.js App (Frontend)"
        Pages["Pages & Layouts\n(src/app)"]:::frontend
        Components["UI Components\n(src/components)"]:::frontend
        Context["UserContext\n(src/context/UserContext.tsx)"]:::frontend
        Styling["Styling (Tailwind CSS)\n(src/app/globals.css, tailwind.config.ts)"]:::frontend
        LocalData["Local Bible Data & OpenAPI Spec\n(src/data/NIV.json, openapi/api.bible.openapi3.json)"]:::frontend
    end

    subgraph "Next.js API Layer"
        GetPassage["getPassage Route\n(src/app/api/getPassage/route.ts)"]:::backend
    end

    subgraph "Convex Backend"
        Schema["Schema & Auth Config\n(convex/schema.ts, convex/auth.config.ts)"]:::backend
        Functions["Serverless Functions\n(convex/notes.ts, noteSections.ts, noteSectionAnnotations.ts, noteFreeText.ts, verseTags.ts, users.ts)"]:::backend
        Crons["Cron Jobs & Cleanup\n(convex/cleanupNotes.ts, convex/crons.js)"]:::backend
        Bindings["Generated Bindings\n(convex/_generated/api.js, server.js, *.d.ts)"]:::backend
    end

    DB["Convex Database"]:::database

    External["External Bible API\n(openapi/api.bible.json)"]:::external

    subgraph "CI/CD & Hosting"
        CI["GitHub Actions\n(.github/workflows/*.yaml)"]:::cicd
        Vercel["Vercel"]:::cicd
    end

    Browser -->|"SSR/SSG & CSR"| Pages
    Pages -->|"HTTP GET /api/getPassage"| GetPassage
    GetPassage -->|"read local JSON"| LocalData
    GetPassage -->|"proxy HTTP"| External
    Pages -->|"Convex RPC"| Functions
    Components -->|"Convex RPC"| Functions
    Context -->|"provides state"| Components
    Functions -->|"reads/writes"| DB
    Crons -->|"cron trigger"| Functions
    CI -->|"deploy"| Vercel

    click Pages "https://github.com/madrym/parakletos/tree/main/src/app"
    click Components "https://github.com/madrym/parakletos/tree/main/src/components"
    click Context "https://github.com/madrym/parakletos/blob/main/src/context/UserContext.tsx"
    click Styling "https://github.com/madrym/parakletos/blob/main/src/app/globals.css"
    click LocalData "https://github.com/madrym/parakletos/blob/main/src/data/NIV.json"
    click GetPassage "https://github.com/madrym/parakletos/blob/main/src/app/api/getPassage/route.ts"
    click Schema "https://github.com/madrym/parakletos/blob/main/convex/schema.ts"
    click Schema "https://github.com/madrym/parakletos/blob/main/convex/auth.config.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/notes.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/noteSections.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/noteSectionAnnotations.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/noteFreeText.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/verseTags.ts"
    click Functions "https://github.com/madrym/parakletos/blob/main/convex/users.ts"
    click Crons "https://github.com/madrym/parakletos/blob/main/convex/cleanupNotes.ts"
    click Crons "https://github.com/madrym/parakletos/blob/main/convex/crons.js"
    click Bindings "https://github.com/madrym/parakletos/blob/main/convex/_generated/api.js"
    click Bindings "https://github.com/madrym/parakletos/blob/main/convex/_generated/server.js"
    click Bindings "https://github.com/madrym/parakletos/blob/main/convex/_generated/*.d.ts"
    click External "https://github.com/madrym/parakletos/blob/main/openapi/api.bible.json"
    click CI "https://github.com/madrym/parakletos/blob/main/.github/workflows/codeql.yml"
    click CI "https://github.com/madrym/parakletos/blob/main/.github/workflows/vercel-preview.yaml"
    click CI "https://github.com/madrym/parakletos/blob/main/.github/workflows/vercel-prod.yaml"

    classDef frontend fill:#E0F7FF,stroke:#00AEEF,stroke-width:1px
    classDef backend fill:#E8F8E0,stroke:#28A745,stroke-width:1px
    classDef database fill:#FFF4E0,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 5 5
    classDef cicd fill:#F3E5FF,stroke:#800080,stroke-width:1px
```
