rjmad1/careerpropel

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.