# rjmad1/careerpropel architecture

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

- Interactive diagram: https://gitdiagram.com/rjmad1/careerpropel
- Repository: https://github.com/rjmad1/careerpropel

## Overview

1. **System shape**
   - This repository is a **Next.js 14 / React 18 / TypeScript** application centered on a career-management dashboard.
   - The architecture is primarily **frontend-driven**, with a clear separation between page composition, domain components, shared UI primitives, and integration layers.

2. **Primary entry points**
   - `src/app/layout.tsx` and `src/app/page.tsx` are the top-level App Router entry points.
   - `src/components/Layout/AppLayout.tsx` likely provides the persistent shell around the main workspace, while the page itself hosts the core dashboard experience.

3. **Main product surface**
   - The core experience is a **Kanban / swimlane job pipeline** with supporting views for agent activity, notifications, and analytics.
   - The readme describes a 14-stage pipeline, and the file tree confirms the dashboard is organized around `src/components/Kanban`, `src/components/Agent`, `src/components/Notifications`, and `src/components/analytics`.

4. **Domain-specific UI subsystems**
   - `Kanban/` contains board-level composition and item rendering: `KanbanBoard`, `Swimlane`, and `JobCard`.
   - `Agent/` visualizes autonomous workflow activity through `AgentCard`, `AgentLog`, and `AgentRail`.
   - `Notifications/` handles in-app alerting and toast delivery.
   - `analytics/` contains export actions, suggesting reporting is a first-class feature rather than a background concern.

5. **State and interaction model**
   - `src/hooks/useJobBoard.ts` is the likely coordinator for board data, filtering, drag-and-drop state, and optimistic updates.
   - `src/hooks/useRealTime.ts` suggests a separate synchronization layer for live events, keeping the UI updated without full refreshes.
   - Together, these hooks imply the app is organized around **client-side state orchestration plus live event reconciliation**.

6. **Integration boundary**
   - `src/lib/api/client.ts` is the generic HTTP/API access layer.
   - `src/lib/websocket/client.ts` and `src/lib/websocket/types.ts` define the real-time transport boundary and event contracts.
   - The architecture separates **request/response data fetching** from **push-based synchronization**, which is important for the board’s live behavior.

7. **Cross-cutting services**
   - `src/lib/notifications/manager.ts` centralizes notification logic rather than embedding it in individual components.
   - `src/lib/analytics/export.ts` indicates analytics output is handled as a shared service, likely feeding export buttons and reporting workflows.
   - `src/lib/config.ts`, `src/lib/utils.ts`, and `src/lib/design-tokens.ts` provide shared configuration, helpers, and visual consistency.

8. **Data model and type contracts**
   - `prisma/schema.prisma` defines the persistence schema, which is the main source of truth for jobs, agents, and related records.
   - `src/types/job.ts`, `src/types/agent.ts`, and `src/types/index.ts` provide typed domain contracts for the UI and integration layers.
   - This suggests the app keeps **database schema, transport payloads, and UI models** closely aligned.

9. **UI foundation**
   - `src/components/ui/` contains the design-system primitives: buttons, cards, inputs, badges, modals, spinners, and so on.
   - Tailwind is part of the styling stack, with `tailwind.config.js` and design tokens likely used to enforce consistency across the dashboard.

10. **Forms and workflow controls**
   - `src/components/forms/AdvancedJobFilterForm.tsx` indicates the board is not just static display; it supports richer query and filtering workflows.
   - This sits between the user-facing board and the job-board state layer, shaping how records are narrowed and acted on.

11. **Quality and validation**
   - Cypress end-to-end tests cover the key user journeys: kanban behavior, drag-and-drop, filters, notifications, realtime updates, analytics, and agent visibility.
   - `lighthouse.config.js` and `lighthouse-budget.json` show performance budgets are part of the architecture, not an afterthought.

12. **Operational support**
   - The repo includes backup/runbook documentation and `scripts/weekly-backup.sh`, which indicates production operations are considered part of the system design.
   - The readme also references Docker, PostgreSQL, Redis, OAuth, and monitoring/tracing infrastructure, but those are not fully represented in the visible source tree here; they should be treated as the intended runtime environment and service boundaries rather than as locally implemented modules.

13. **How data flows through the app**
   - User actions start in the dashboard UI, move through feature hooks, then into API or websocket clients.
   - Responses and live events update shared state, which re-renders kanban lanes, agent panels, notifications, and analytics surfaces.
   - Persistence is modeled through Prisma, while real-time updates are handled separately so the board can stay responsive under concurrent changes.

14. **How to diagram it**
   - A good architecture diagram would show a **single Next.js front end** composed of domain modules, backed by **typed API and websocket integration layers**, with **Prisma-backed persistence** and **live synchronization/notification services** as the main external boundaries.

Main entry points: [`src/components/Kanban/KanbanBoard.tsx`](https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/KanbanBoard.tsx) (Kanban board), [`src/app/page.tsx`](https://github.com/rjmad1/careerpropel/blob/main/src/app/page.tsx) (Dashboard page), [`src/hooks/useJobBoard.ts`](https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useJobBoard.ts) (Job board hook), [`src/hooks/useRealTime.ts`](https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useRealTime.ts) (Realtime hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App shell"]
  node_n_layout["App layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_n_page["Dashboard page<br/>Next.js route<br/>[page.tsx]"]
  node_n_shell["Workspace shell<br/>layout component<br/>[AppLayout.tsx]"]
end

subgraph group_g_domain["Product UI"]
  node_n_board["Kanban board<br/>feature component<br/>[KanbanBoard.tsx]"]
  node_n_swimlane["Swimlanes<br/>feature component<br/>[Swimlane.tsx]"]
  node_n_jobcard["Job card<br/>feature component<br/>[JobCard.tsx]"]
  node_n_filters["Job filters<br/>form component"]
  node_n_agentcard["Agent card<br/>agent view<br/>[AgentCard.tsx]"]
  node_n_agentlog["Agent log<br/>agent view<br/>[AgentLog.tsx]"]
  node_n_agentr["Agent rail<br/>agent view<br/>[AgentRail.tsx]"]
  node_n_notify["Notifications<br/>alert center"]
  node_n_toast["Toast<br/>alert component<br/>[Toast.tsx]"]
  node_n_analytics["Analytics export<br/>reporting UI"]
end

subgraph group_g_integration["Integration"]
  node_n_jobhook["Job board hook<br/>state hook<br/>[useJobBoard.ts]"]
  node_n_realtimehook["Realtime hook<br/>sync hook<br/>[useRealTime.ts]"]
  node_n_apiclient["API client<br/>http client<br/>[client.ts]"]
  node_n_wsclient["WebSocket client<br/>realtime transport<br/>[client.ts]"]
  node_n_notifmgr["Notification manager<br/>[manager.ts]"]
  node_n_anaexport["Export service<br/>[export.ts]"]
end

subgraph group_g_data["Data and ops"]
  node_n_prisma[("Prisma schema<br/>data model<br/>[schema.prisma]")]
  node_n_types_job["Job types<br/>domain types<br/>[job.ts]"]
  node_n_types_agent["Agent types<br/>domain types<br/>[agent.ts]"]
  node_n_design["Design tokens<br/>style system<br/>[design-tokens.ts]"]
  node_n_config["Config<br/>[config.ts]"]
end

node_n_layout -->|"composes"| node_n_shell
node_n_layout -->|"hosts"| node_n_page
node_n_page -->|"renders"| node_n_board
node_n_page -->|"shows"| node_n_agentcard
node_n_page -->|"shows"| node_n_notify
node_n_page -->|"shows"| node_n_analytics
node_n_shell -->|"frames"| node_n_board
node_n_board -->|"organizes"| node_n_swimlane
node_n_board -->|"renders"| node_n_jobcard
node_n_board -->|"filters by"| node_n_filters
node_n_filters -->|"updates"| node_n_jobhook
node_n_jobhook -->|"fetches"| node_n_apiclient
node_n_jobhook -->|"reflects"| node_n_prisma
node_n_realtimehook -->|"subscribes to"| node_n_wsclient
node_n_realtimehook -->|"reconciles"| node_n_jobhook
node_n_realtimehook -->|"triggers"| node_n_notifmgr
node_n_notify -->|"uses"| node_n_notifmgr
node_n_notify -->|"displays"| node_n_toast
node_n_analytics -->|"uses"| node_n_anaexport
node_n_agentcard -->|"drills into"| node_n_agentlog
node_n_agentcard -->|"surfaces"| node_n_agentr
node_n_board -->|"types"| node_n_types_job
node_n_agentcard -->|"types"| node_n_types_agent
node_n_jobhook -->|"consumes"| node_n_types_job
node_n_realtimehook -->|"consumes"| node_n_types_agent
node_n_shell -->|"styles"| node_n_design
node_n_board -->|"styles"| node_n_design
node_n_apiclient -->|"reads"| node_n_config

click node_n_layout "https://github.com/rjmad1/careerpropel/blob/main/src/app/layout.tsx"
click node_n_page "https://github.com/rjmad1/careerpropel/blob/main/src/app/page.tsx"
click node_n_shell "https://github.com/rjmad1/careerpropel/blob/main/src/components/Layout/AppLayout.tsx"
click node_n_board "https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/KanbanBoard.tsx"
click node_n_swimlane "https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/Swimlane.tsx"
click node_n_jobcard "https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/JobCard.tsx"
click node_n_filters "https://github.com/rjmad1/careerpropel/blob/main/src/components/forms/AdvancedJobFilterForm.tsx"
click node_n_agentcard "https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentCard.tsx"
click node_n_agentlog "https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentLog.tsx"
click node_n_agentr "https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentRail.tsx"
click node_n_notify "https://github.com/rjmad1/careerpropel/blob/main/src/components/Notifications/NotificationCenter.tsx"
click node_n_toast "https://github.com/rjmad1/careerpropel/blob/main/src/components/Notifications/Toast.tsx"
click node_n_analytics "https://github.com/rjmad1/careerpropel/blob/main/src/components/analytics/AnalyticsExportButtons.tsx"
click node_n_jobhook "https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useJobBoard.ts"
click node_n_realtimehook "https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useRealTime.ts"
click node_n_apiclient "https://github.com/rjmad1/careerpropel/blob/main/src/lib/api/client.ts"
click node_n_wsclient "https://github.com/rjmad1/careerpropel/blob/main/src/lib/websocket/client.ts"
click node_n_notifmgr "https://github.com/rjmad1/careerpropel/blob/main/src/lib/notifications/manager.ts"
click node_n_anaexport "https://github.com/rjmad1/careerpropel/blob/main/src/lib/analytics/export.ts"
click node_n_prisma "https://github.com/rjmad1/careerpropel/blob/main/prisma/schema.prisma"
click node_n_types_job "https://github.com/rjmad1/careerpropel/blob/main/src/types/job.ts"
click node_n_types_agent "https://github.com/rjmad1/careerpropel/blob/main/src/types/agent.ts"
click node_n_design "https://github.com/rjmad1/careerpropel/blob/main/src/lib/design-tokens.ts"
click node_n_config "https://github.com/rjmad1/careerpropel/blob/main/src/lib/config.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_n_layout,node_n_page,node_n_shell toneBlue
class node_n_board,node_n_swimlane,node_n_jobcard,node_n_filters,node_n_agentcard,node_n_agentlog,node_n_agentr,node_n_notify,node_n_toast,node_n_analytics toneAmber
class node_n_jobhook,node_n_realtimehook,node_n_apiclient,node_n_wsclient,node_n_notifmgr,node_n_anaexport toneMint
class node_n_prisma,node_n_types_job,node_n_types_agent,node_n_design,node_n_config toneRose
```

## Components

### App shell

Next.js entry points and persistent layout composition

- [App layout](https://github.com/rjmad1/careerpropel/blob/main/src/app/layout.tsx): Next.js shell · Root app router layout and global composition · `src/app/layout.tsx`
- [Dashboard page](https://github.com/rjmad1/careerpropel/blob/main/src/app/page.tsx): Next.js route · Main routed dashboard experience · `src/app/page.tsx`
- [Workspace shell](https://github.com/rjmad1/careerpropel/blob/main/src/components/Layout/AppLayout.tsx): layout component · Persistent application chrome and page framing · `src/components/Layout/AppLayout.tsx`

### Product UI

Core dashboard features and shared interaction surfaces

- [Kanban board](https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/KanbanBoard.tsx): feature component · Primary job pipeline view with lanes and cards · `src/components/Kanban/KanbanBoard.tsx`
- [Swimlanes](https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/Swimlane.tsx): feature component · Lane grouping and pipeline structure · `src/components/Kanban/Swimlane.tsx`
- [Job card](https://github.com/rjmad1/careerpropel/blob/main/src/components/Kanban/JobCard.tsx): feature component · Individual job item presentation and actions · `src/components/Kanban/JobCard.tsx`
- [Job filters](https://github.com/rjmad1/careerpropel/blob/main/src/components/forms/AdvancedJobFilterForm.tsx): form component · Advanced filtering and query controls · `src/components/forms/AdvancedJobFilterForm.tsx`
- [Agent card](https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentCard.tsx): agent view · Autonomous agent status and activity summary · `src/components/Agent/AgentCard.tsx`
- [Agent log](https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentLog.tsx): agent view · Agent event and execution history · `src/components/Agent/AgentLog.tsx`
- [Agent rail](https://github.com/rjmad1/careerpropel/blob/main/src/components/Agent/AgentRail.tsx): agent view · Compact activity rail for agent monitoring · `src/components/Agent/AgentRail.tsx`
- [Notifications](https://github.com/rjmad1/careerpropel/blob/main/src/components/Notifications/NotificationCenter.tsx): alert center · In-app notification center and toast delivery · `src/components/Notifications/NotificationCenter.tsx`
- [Toast](https://github.com/rjmad1/careerpropel/blob/main/src/components/Notifications/Toast.tsx): alert component · Transient notification presentation · `src/components/Notifications/Toast.tsx`
- [Analytics export](https://github.com/rjmad1/careerpropel/blob/main/src/components/analytics/AnalyticsExportButtons.tsx): reporting UI · Export actions for analytics and reporting · `src/components/analytics/AnalyticsExportButtons.tsx`

### Integration

Client, realtime, and cross-cutting service boundaries

- [Job board hook](https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useJobBoard.ts): state hook · Board state, filtering, drag-and-drop, optimistic updates · `src/hooks/useJobBoard.ts`
- [Realtime hook](https://github.com/rjmad1/careerpropel/blob/main/src/hooks/useRealTime.ts): sync hook · Live event subscription and UI reconciliation · `src/hooks/useRealTime.ts`
- [API client](https://github.com/rjmad1/careerpropel/blob/main/src/lib/api/client.ts): http client · Request/response integration boundary · `src/lib/api/client.ts`
- [WebSocket client](https://github.com/rjmad1/careerpropel/blob/main/src/lib/websocket/client.ts): realtime transport · Push transport for live updates · `src/lib/websocket/client.ts`
- [Notification manager](https://github.com/rjmad1/careerpropel/blob/main/src/lib/notifications/manager.ts): service · Central notification orchestration · `src/lib/notifications/manager.ts`
- [Export service](https://github.com/rjmad1/careerpropel/blob/main/src/lib/analytics/export.ts): service · Shared analytics export logic · `src/lib/analytics/export.ts`

### Data and ops

Persistence model, validation, and operational support

- [Prisma schema](https://github.com/rjmad1/careerpropel/blob/main/prisma/schema.prisma): data model · Persistence schema for jobs, agents, and related records · `prisma/schema.prisma`
- [Job types](https://github.com/rjmad1/careerpropel/blob/main/src/types/job.ts): domain types · Typed job contracts shared across the UI · `src/types/job.ts`
- [Agent types](https://github.com/rjmad1/careerpropel/blob/main/src/types/agent.ts): domain types · Typed agent contracts shared across the UI · `src/types/agent.ts`
- [Design tokens](https://github.com/rjmad1/careerpropel/blob/main/src/lib/design-tokens.ts): style system · Shared visual constants and theme primitives · `src/lib/design-tokens.ts`
- [Config](https://github.com/rjmad1/careerpropel/blob/main/src/lib/config.ts): shared config · Application configuration and environment wiring · `src/lib/config.ts`

## Connections

- App layout → Workspace shell: composes · Root layout wraps the persistent application shell
- App layout → Dashboard page: hosts · App router renders the dashboard page inside the layout
- Dashboard page → Kanban board: renders · Main page centers on the kanban pipeline
- Dashboard page → Agent card: shows · Dashboard surface includes agent monitoring
- Dashboard page → Notifications: shows · Dashboard surface includes notifications
- Dashboard page → Analytics export: shows · Dashboard surface exposes export/reporting actions
- Workspace shell → Kanban board: frames · Workspace shell provides consistent page chrome around the board
- Kanban board → Swimlanes: organizes · Board is structured into swimlanes
- Kanban board → Job card: renders · Board displays individual jobs as cards
- Kanban board → Job filters: filters by · Board supports advanced filtering controls
- Job filters → Job board hook: updates · Filter state feeds the job board hook
- Job board hook → API client: fetches · Board state layer loads and mutates data through API calls
- Job board hook → Prisma schema: reflects · Board logic mirrors persisted job and workflow records
- Realtime hook → WebSocket client: subscribes to · Realtime hook listens to websocket events
- Realtime hook → Job board hook: reconciles · Live events update board state
- Realtime hook → Notification manager: triggers · Incoming events can surface notifications
- Notifications → Notification manager: uses · Notification center relies on shared notification orchestration
- Notifications → Toast: displays · Notification center renders toast feedback
- Analytics export → Export service: uses · Export buttons call the shared export service
- Agent card → Agent log: drills into · Agent summary connects to detailed logs
- Agent card → Agent rail: surfaces · Agent summary also feeds the activity rail
- Kanban board → Job types: types · Kanban UI is driven by job domain contracts
- Agent card → Agent types: types · Agent UI is driven by agent domain contracts
- Job board hook → Job types: consumes · Board state logic uses job contracts
- Realtime hook → Agent types: consumes · Realtime layer exchanges agent-related event types
- Workspace shell → Design tokens: styles · Layout and shared components use design tokens
- Kanban board → Design tokens: styles · Kanban visuals follow shared tokens
- API client → Config: reads · API client depends on shared configuration