How madrym/parakletos works
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