# severusjr/jtalks architecture

> Architecture diagram of the GitHub repository severusjr/jtalks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/severusjr/jtalks
- Repository: https://github.com/severusjr/jtalks

## Overview

#### Purpose and Entry Points
TechMeet Scheduler is an internal weekly-session scheduling system with role-based administration and team self-service. Next.js App Router provides both UI and REST endpoints. Root routing begins at `app/page.tsx`; authentication screens are under `app/(auth)/login/page.tsx`; protected product navigation is organized under `app/(dashboard)/layout.tsx` and dashboard routes such as `app/(dashboard)/dashboard/page.tsx`.

#### UI Application Shell
The dashboard route group supplies the authenticated application frame, with shared navigation and responsive layout components in `components/layout/DashboardLayout.tsx`, `components/layout/Sidebar.tsx`, and `components/layout/Header.tsx`. Feature pages render calendar, application, session, reporting, team, settings, and admin workflows. Shared modal and presentation primitives in `components/ui/Modal.tsx`, `components/ui/Card.tsx`, and `components/ui/ConfirmDialog.tsx` support those workflows.

#### Identity, Authorization, and Route Boundary
Authentication is split between client-facing auth state and server/API enforcement: `hooks/useAuth.tsx`, `lib/auth.ts`, and `lib/server-auth.ts`. Catalyst-specific authentication integration is represented by `lib/catalyst-auth.ts`; login/password-reset UI and API endpoints are at `app/(auth)/login/page.tsx`, `app/api/auth/me/route.ts`, and `app/api/auth/reset-password/route.ts`. Admin-facing routes (`app/(dashboard)/admin/page.tsx`) are a critical role boundary from team-user workflows.

#### Scheduling and Session Lifecycle
Sessions are the central domain object: list/detail UI resides in `app/(dashboard)/sessions/page.tsx` and `app/(dashboard)/sessions/[id]/page.tsx`, while CRUD is exposed through `app/api/sessions/route.ts` and `app/api/sessions/[id]/route.ts`. Domain normalization and state derivation are concentrated in `lib/materializeSession.ts`, `lib/sessionStatus.ts`, and `lib/sessionMeta.ts`. Calendar/schedule management flows through `app/(dashboard)/calendar/page.tsx` and `app/api/schedules/route.ts`; the lifecycle moves availability into assignment, completion, or cancellation.

#### Applications and Administrative Assignment
Teams submit preferred-date/presenter requests through `components/applications/ApplyForDayModal.tsx`, backed by `app/api/applications/route.ts` and `app/api/applications/[id]/route.ts`. Client data ownership is encapsulated by `contexts/ApplicationsContext.tsx` and `hooks/useApplications.ts`. Administrators review applications, assign sessions, and manage teams using `app/(dashboard)/admin/page.tsx`, `app/(dashboard)/admin/teams/page.tsx`, and `app/api/teams/route.ts`.

#### Collaboration, Recordings, and Reporting
Session detail supports threaded comments and recording access. The API boundary is `app/api/sessions/[id]/comments/route.ts`, `app/api/sessions/[id]/recording/route.ts`, and `app/api/sessions/[id]/recording/direct/route.ts`; UI is in `components/sessions/CommentsDrawer.tsx` and `components/sessions/RecordingPlayerModal.tsx`. Recording URL construction/storage behavior is isolated in `lib/recordingLink.ts` and `lib/recordings.ts`. Aggregate reporting is served by `app/api/reports/route.ts` and displayed at `app/(dashboard)/reports/page.tsx`.

#### Persistence and Deployment Runtime
The primary production persistence model is Prisma/PostgreSQL, defined in `prisma/schema.prisma` and accessed through `lib/prisma.ts`; `prisma/seed.ts` supports initial data. The repository also includes Zoho Catalyst deployment/integration artifacts: `catalyst.json`, `.catalystrc`, `lib/catalyst.ts`, and `server-appsail.js`, with deployment/setup documentation in `DEPLOY-CATALYST.md` and `CATALYST-DATASTORE-SETUP.md`. Demo/mock data remains available in `lib/mockData.ts`, creating an explicit boundary between local/demo behavior and database-backed production behavior.

Main entry points: [`app/(dashboard)/layout.tsx`](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/layout.tsx) (Protected dashboard), [`prisma/schema.prisma`](https://github.com/severusjr/jtalks/blob/main/prisma/schema.prisma) (PostgreSQL via Prisma), [`app/api/applications/route.ts`](https://github.com/severusjr/jtalks/blob/main/app/api/applications/route.ts) (Applications API), [`app/(dashboard)/admin/page.tsx`](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/admin/page.tsx) (Admin & teams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_root["Root entry<br/>Next.js page<br/>[page.tsx]"]
  node_auth_ui["Login &amp; reset UI<br/>auth pages<br/>[page.tsx]"]
  node_dashboard["Protected dashboard<br/>route shell<br/>[layout.tsx]"]
  node_dashboard_layout["Dashboard layout components<br/>UI shell"]
  node_sessions_ui["Sessions UI<br/>feature pages<br/>[page.tsx]"]
  node_calendar_ui["Calendar UI<br/>feature page<br/>[page.tsx]"]
  node_applications_ui["Application submission<br/>modal workflow"]
  node_admin_ui["Admin &amp; teams<br/>admin pages<br/>[page.tsx]"]
  node_collaboration_ui["Comments &amp; recordings<br/>session UI<br/>[CommentsDrawer.tsx]"]
  node_reports_ui["Reports UI<br/>feature page<br/>[page.tsx]"]
end

subgraph group_api["API &amp; domain"]
  node_auth{{"Authentication boundary<br/>auth services<br/>[auth.ts]"}}
  node_auth_api["Auth endpoints<br/>REST routes<br/>[route.ts]"]
  node_sessions_api["Sessions API<br/>REST routes<br/>[route.ts]"]
  node_session_domain["Session lifecycle logic<br/>domain services"]
  node_schedules_api["Schedules API<br/>REST route<br/>[route.ts]"]
  node_applications_api["Applications API<br/>REST routes<br/>[route.ts]"]
  node_teams_api["Teams API<br/>REST route<br/>[route.ts]"]
  node_collaboration_api["Comments &amp; recordings API<br/>nested REST routes<br/>[route.ts]"]
  node_reports_api["Reports API<br/>REST route<br/>[route.ts]"]
end

subgraph group_data["Data &amp; runtime"]
  node_database[("PostgreSQL via Prisma<br/>production persistence<br/>[schema.prisma]")]
  node_catalyst{{"Zoho Catalyst runtime<br/>deployment integration<br/>[catalyst.ts]"}}
  node_mock_data[("Demo/mock data<br/>local data source<br/>[mockData.ts]")]
end

node_root --> node_auth_ui
node_auth_ui -->|"sign in / reset"| node_auth_api
node_auth_api -->|"enforces"| node_auth
node_auth -->|"protects"| node_dashboard
node_dashboard -->|"renders"| node_dashboard_layout
node_dashboard --> node_sessions_ui
node_dashboard --> node_calendar_ui
node_dashboard -->|"admin role"| node_admin_ui
node_dashboard --> node_reports_ui
node_sessions_ui -->|"CRUD"| node_sessions_api
node_calendar_ui -->|"manage availability"| node_schedules_api
node_applications_ui -->|"submit requests"| node_applications_api
node_admin_ui -->|"review / assign"| node_applications_api
node_admin_ui -->|"manage teams"| node_teams_api
node_collaboration_ui -->|"comments / recordings"| node_collaboration_api
node_reports_ui -->|"aggregate data"| node_reports_api
node_applications_api -->|"assignment creates sessions"| node_sessions_api
node_schedules_api -->|"availability state"| node_session_domain
node_sessions_api -->|"normalize / derive status"| node_session_domain
node_session_domain -->|"persisted sessions"| node_database
node_applications_api --> node_database
node_teams_api --> node_database
node_collaboration_api --> node_database
node_reports_api --> node_database
node_auth -.->|"Catalyst auth integration"| node_catalyst
node_catalyst -.->|"deployment integration"| node_database
node_mock_data -.->|"local/demo alternative"| node_database

click node_root "https://github.com/severusjr/jtalks/blob/main/app/page.tsx"
click node_auth_ui "https://github.com/severusjr/jtalks/blob/main/app/(auth)/login/page.tsx"
click node_dashboard "https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/layout.tsx"
click node_dashboard_layout "https://github.com/severusjr/jtalks/blob/main/components/layout/DashboardLayout.tsx"
click node_sessions_ui "https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/sessions/page.tsx"
click node_calendar_ui "https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/calendar/page.tsx"
click node_applications_ui "https://github.com/severusjr/jtalks/blob/main/components/applications/ApplyForDayModal.tsx"
click node_admin_ui "https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/admin/page.tsx"
click node_collaboration_ui "https://github.com/severusjr/jtalks/blob/main/components/sessions/CommentsDrawer.tsx"
click node_reports_ui "https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/reports/page.tsx"
click node_auth "https://github.com/severusjr/jtalks/blob/main/lib/auth.ts"
click node_auth_api "https://github.com/severusjr/jtalks/blob/main/app/api/auth/me/route.ts"
click node_sessions_api "https://github.com/severusjr/jtalks/blob/main/app/api/sessions/route.ts"
click node_session_domain "https://github.com/severusjr/jtalks/blob/main/lib/materializeSession.ts"
click node_schedules_api "https://github.com/severusjr/jtalks/blob/main/app/api/schedules/route.ts"
click node_applications_api "https://github.com/severusjr/jtalks/blob/main/app/api/applications/route.ts"
click node_teams_api "https://github.com/severusjr/jtalks/blob/main/app/api/teams/route.ts"
click node_collaboration_api "https://github.com/severusjr/jtalks/blob/main/app/api/sessions/%5Bid%5D/comments/route.ts"
click node_reports_api "https://github.com/severusjr/jtalks/blob/main/app/api/reports/route.ts"
click node_database "https://github.com/severusjr/jtalks/blob/main/prisma/schema.prisma"
click node_catalyst "https://github.com/severusjr/jtalks/blob/main/lib/catalyst.ts"
click node_mock_data "https://github.com/severusjr/jtalks/blob/main/lib/mockData.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_auth_ui,node_dashboard,node_dashboard_layout,node_sessions_ui,node_calendar_ui,node_applications_ui,node_admin_ui,node_collaboration_ui,node_reports_ui toneBlue
class node_auth,node_auth_api,node_sessions_api,node_session_domain,node_schedules_api,node_applications_api,node_teams_api,node_collaboration_api,node_reports_api toneAmber
class node_database,node_catalyst,node_mock_data toneMint
```

## Components

### Next.js UI

App Router pages and shared client workflows.

- [Root entry](https://github.com/severusjr/jtalks/blob/main/app/page.tsx): Next.js page · `app/page.tsx`
- [Login & reset UI](https://github.com/severusjr/jtalks/blob/main/app/(auth)/login/page.tsx): auth pages · `app/(auth)/login/page.tsx`
- [Protected dashboard](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/layout.tsx): route shell · Authenticated navigation and responsive layout. · `app/(dashboard)/layout.tsx`
- [Dashboard layout components](https://github.com/severusjr/jtalks/blob/main/components/layout/DashboardLayout.tsx): UI shell · `components/layout/DashboardLayout.tsx`
- [Sessions UI](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/sessions/page.tsx): feature pages · List and detail views for the session lifecycle. · `app/(dashboard)/sessions/page.tsx`
- [Calendar UI](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/calendar/page.tsx): feature page · `app/(dashboard)/calendar/page.tsx`
- [Application submission](https://github.com/severusjr/jtalks/blob/main/components/applications/ApplyForDayModal.tsx): modal workflow · `components/applications/ApplyForDayModal.tsx`
- [Admin & teams](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/admin/page.tsx): admin pages · Role-restricted assignment and team management. · `app/(dashboard)/admin/page.tsx`
- [Comments & recordings](https://github.com/severusjr/jtalks/blob/main/components/sessions/CommentsDrawer.tsx): session UI · `components/sessions/CommentsDrawer.tsx`
- [Reports UI](https://github.com/severusjr/jtalks/blob/main/app/(dashboard)/reports/page.tsx): feature page · `app/(dashboard)/reports/page.tsx`

### API & domain

Server route handlers and scheduling logic.

- [Authentication boundary](https://github.com/severusjr/jtalks/blob/main/lib/auth.ts): auth services · Client state and server/API authorization enforcement. · `lib/auth.ts`
- [Auth endpoints](https://github.com/severusjr/jtalks/blob/main/app/api/auth/me/route.ts): REST routes · `app/api/auth/me/route.ts`
- [Sessions API](https://github.com/severusjr/jtalks/blob/main/app/api/sessions/route.ts): REST routes · Session CRUD endpoints. · `app/api/sessions/route.ts`
- [Session lifecycle logic](https://github.com/severusjr/jtalks/blob/main/lib/materializeSession.ts): domain services · Normalizes sessions and derives lifecycle state. · `lib/materializeSession.ts`
- [Schedules API](https://github.com/severusjr/jtalks/blob/main/app/api/schedules/route.ts): REST route · Availability and schedule management. · `app/api/schedules/route.ts`
- [Applications API](https://github.com/severusjr/jtalks/blob/main/app/api/applications/route.ts): REST routes · `app/api/applications/route.ts`
- [Teams API](https://github.com/severusjr/jtalks/blob/main/app/api/teams/route.ts): REST route · `app/api/teams/route.ts`
- [Comments & recordings API](https://github.com/severusjr/jtalks/blob/main/app/api/sessions/%5Bid%5D/comments/route.ts): nested REST routes · Session collaboration and recording access. · `app/api/sessions/[id]/comments/route.ts`
- [Reports API](https://github.com/severusjr/jtalks/blob/main/app/api/reports/route.ts): REST route · `app/api/reports/route.ts`

### Data & runtime

Production persistence and deployment integrations.

- [PostgreSQL via Prisma](https://github.com/severusjr/jtalks/blob/main/prisma/schema.prisma): production persistence · Prisma schema and database client. · `prisma/schema.prisma`
- [Zoho Catalyst runtime](https://github.com/severusjr/jtalks/blob/main/lib/catalyst.ts): deployment integration · Catalyst authentication and deployment environment. · `lib/catalyst.ts`
- [Demo/mock data](https://github.com/severusjr/jtalks/blob/main/lib/mockData.ts): local data source · Explicit non-production data boundary. · `lib/mockData.ts`

## Connections

- Root entry → Login & reset UI
- Login & reset UI → Auth endpoints: sign in / reset
- Auth endpoints → Authentication boundary: enforces
- Authentication boundary → Protected dashboard: protects
- Protected dashboard → Dashboard layout components: renders
- Protected dashboard → Sessions UI
- Protected dashboard → Calendar UI
- Protected dashboard → Admin & teams: admin role
- Protected dashboard → Reports UI
- Sessions UI → Sessions API: CRUD
- Calendar UI → Schedules API: manage availability
- Application submission → Applications API: submit requests
- Admin & teams → Applications API: review / assign
- Admin & teams → Teams API: manage teams
- Comments & recordings → Comments & recordings API: comments / recordings
- Reports UI → Reports API: aggregate data
- Applications API → Sessions API: assignment creates sessions
- Schedules API → Session lifecycle logic: availability state
- Sessions API → Session lifecycle logic: normalize / derive status
- Session lifecycle logic → PostgreSQL via Prisma: persisted sessions
- Applications API → PostgreSQL via Prisma
- Teams API → PostgreSQL via Prisma
- Comments & recordings API → PostgreSQL via Prisma
- Reports API → PostgreSQL via Prisma
- Authentication boundary → Zoho Catalyst runtime: Catalyst auth integration
- Zoho Catalyst runtime → PostgreSQL via Prisma: deployment integration
- Demo/mock data → PostgreSQL via Prisma: local/demo alternative