# machadop1407/job-application-tracker architecture

> Architecture diagram of the GitHub repository machadop1407/job-application-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/machadop1407/job-application-tracker
- Repository: https://github.com/machadop1407/job-application-tracker

## Overview

1. This is a single Next.js full-stack app, not a split frontend/backend system. The App Router drives both the public marketing pages and the authenticated dashboard, while server actions and one auth API route handle the backend behavior.

2. The app is organized around three top-level user surfaces:
   - `/` as the landing page
   - `/sign-in` and `/sign-up` for authentication
   - `/dashboard` for the actual job-tracking workspace

3. The dashboard is the core product boundary. It renders a Kanban board for a user’s job hunt and is the only place where board data, drag-and-drop, and mutations come together. The board is personalized per user and is expected to be unavailable unless the user is authenticated.

4. Data persistence is MongoDB via Mongoose, with the database connection centralized in `lib/db.ts`. The model layer in `lib/models/` defines the main domain objects:
   - Board
   - Column
   - JobApplication  
   The relationships are hierarchical: one board contains columns, and columns contain job applications.

5. Authentication uses Better Auth in `lib/auth/auth.ts`, with a MongoDB adapter so users and sessions live in the same database. The route `app/api/auth/[...all]/route.ts` exposes the auth endpoints, and `lib/auth/auth-client.ts` is the client-side integration point for sign-in/sign-up/session state.

6. A key lifecycle hook is automatic board creation on user signup. The auth configuration triggers `lib/init-user-board.ts`, which initializes the default Kanban structure so every new user gets a ready-to-use board immediately after account creation.

7. Data mutations are handled through server actions in `lib/actions/job-applications.ts`, not through a separate REST API for the job entities. These actions are responsible for create/update/delete operations, session checks, ownership validation, column/order maintenance, and cache invalidation after changes.

8. The board UI is a client-heavy experience built in `components/kanban-board.tsx` with `dnd-kit`. Dragging a job card between columns or within a column updates local state through `lib/hooks/useBoards.ts`, then persists the change back to MongoDB through the server action layer.

9. The rest of `components/` is mostly composition around the board workflow:
   - `create-job-dialog.tsx` for adding jobs
   - `job-application-card.tsx` for displaying each application
   - `navbar.tsx` and `sign-out-btn.tsx` for authenticated navigation
   - `image-tabs.tsx` and `public/hero-images` for presentation on the landing page
   - `components/ui/*` as reusable Radix-based primitives

10. The page layer uses a mix of server and client components. `app/dashboard/page.tsx` is the main server-side data loader, likely fetching the populated board graph and handing it to the board UI. `app/layout.tsx`, `app/globals.css`, and `app/page.tsx` set the global shell and styling for the whole app.

11. Route protection is likely enforced at the edge or middleware layer via `proxy.ts`, which acts as the boundary around authenticated routes and prevents unauthenticated access to the dashboard flow.

12. `scripts/seed.ts` is the offline data bootstrap path. It populates sample boards, columns, and job applications for local development or tutorial demos, but it is not part of the runtime request flow.

13. Overall request/data flow is: user signs in through Better Auth, the session gates the dashboard, the dashboard loads a populated board from MongoDB, user interactions update client state in the Kanban UI, and server actions persist those changes back to the database and refresh the UI.

Main entry points: [`app/dashboard/page.tsx`](https://github.com/machadop1407/job-application-tracker/blob/main/app/dashboard/page.tsx) (Dashboard), [`lib/actions/job-applications.ts`](https://github.com/machadop1407/job-application-tracker/blob/main/lib/actions/job-applications.ts) (Job actions), [`components/kanban-board.tsx`](https://github.com/machadop1407/job-application-tracker/blob/main/components/kanban-board.tsx) (Kanban board), [`app/layout.tsx`](https://github.com/machadop1407/job-application-tracker/blob/main/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["App surfaces"]
  node_app_root["App shell<br/>Next.js app<br/>[layout.tsx]"]
  node_home_page["Landing page<br/>public page<br/>[page.tsx]"]
  node_sign_in_page["Sign in<br/>auth page<br/>[page.tsx]"]
  node_sign_up_page["Sign up<br/>auth page<br/>[page.tsx]"]
  node_dashboard_page["Dashboard<br/>server page<br/>[page.tsx]"]
end

subgraph group_runtime["Runtime flow"]
  node_proxy_guard{{"Route guard<br/>edge proxy<br/>[proxy.ts]"}}
  node_auth_route["Auth API<br/>route handler<br/>[route.ts]"]
  node_auth_core["Auth config<br/>better-auth<br/>[auth.ts]"]
  node_auth_client["Auth client<br/>client auth<br/>[auth-client.ts]"]
  node_board_init["Seed board<br/>signup hook<br/>[init-user-board.ts]"]
  node_boards_hook["Board state<br/>client hook<br/>[useBoards.ts]"]
  node_job_actions["Job actions<br/>server actions"]
end

subgraph group_data["Data layer"]
  node_db_conn[("DB connect<br/>mongoose db<br/>[db.ts]")]
  node_board_model[("Board model<br/>mongoose model<br/>[board.ts]")]
  node_column_model[("Column model<br/>mongoose model<br/>[column.ts]")]
  node_job_model[("Job model<br/>mongoose model<br/>[job-application.ts]")]
  node_model_index["Model index<br/>model barrel<br/>[index.ts]"]
end

subgraph group_shared["Shared UI"]
  node_kanban_board["Kanban board<br/>client UI<br/>[kanban-board.tsx]"]
  node_navbar["Navbar<br/>ui composition<br/>[navbar.tsx]"]
  node_job_card["Job card<br/>board item"]
  node_create_dialog["Create dialog<br/>ui flow"]
  node_ui_primitives["UI primitives<br/>Radix ui<br/>[button.tsx]"]
end

node_app_root -->|"renders"| node_home_page
node_app_root -->|"renders"| node_sign_in_page
node_app_root -->|"renders"| node_sign_up_page
node_app_root -->|"renders"| node_dashboard_page
node_proxy_guard -->|"protects"| node_dashboard_page
node_auth_route -->|"implements"| node_auth_core
node_auth_client -->|"uses"| node_auth_core
node_auth_core -->|"triggers"| node_board_init
node_auth_core -->|"stores in"| node_db_conn
node_board_init -->|"creates"| node_board_model
node_board_init -->|"creates"| node_column_model
node_dashboard_page -->|"loads"| node_db_conn
node_dashboard_page -->|"queries"| node_board_model
node_dashboard_page -->|"queries"| node_column_model
node_dashboard_page -->|"queries"| node_job_model
node_dashboard_page -->|"passes data"| node_kanban_board
node_kanban_board -->|"syncs state"| node_boards_hook
node_kanban_board -->|"composes"| node_job_card
node_kanban_board -->|"opens"| node_create_dialog
node_kanban_board -->|"mutates via"| node_job_actions
node_boards_hook -->|"persists"| node_job_actions
node_job_actions -->|"writes"| node_db_conn
node_job_actions -->|"updates"| node_board_model
node_job_actions -->|"updates"| node_column_model
node_job_actions -->|"updates"| node_job_model
node_navbar -->|"reads session"| node_auth_client
node_navbar -->|"uses"| node_ui_primitives
node_job_card -->|"uses"| node_ui_primitives
node_create_dialog -->|"uses"| node_ui_primitives

click node_app_root "https://github.com/machadop1407/job-application-tracker/blob/main/app/layout.tsx"
click node_home_page "https://github.com/machadop1407/job-application-tracker/blob/main/app/page.tsx"
click node_sign_in_page "https://github.com/machadop1407/job-application-tracker/blob/main/app/sign-in/page.tsx"
click node_sign_up_page "https://github.com/machadop1407/job-application-tracker/blob/main/app/sign-up/page.tsx"
click node_dashboard_page "https://github.com/machadop1407/job-application-tracker/blob/main/app/dashboard/page.tsx"
click node_proxy_guard "https://github.com/machadop1407/job-application-tracker/blob/main/proxy.ts"
click node_auth_route "https://github.com/machadop1407/job-application-tracker/blob/main/app/api/auth/[...all]/route.ts"
click node_auth_core "https://github.com/machadop1407/job-application-tracker/blob/main/lib/auth/auth.ts"
click node_auth_client "https://github.com/machadop1407/job-application-tracker/blob/main/lib/auth/auth-client.ts"
click node_board_init "https://github.com/machadop1407/job-application-tracker/blob/main/lib/init-user-board.ts"
click node_kanban_board "https://github.com/machadop1407/job-application-tracker/blob/main/components/kanban-board.tsx"
click node_boards_hook "https://github.com/machadop1407/job-application-tracker/blob/main/lib/hooks/useBoards.ts"
click node_job_actions "https://github.com/machadop1407/job-application-tracker/blob/main/lib/actions/job-applications.ts"
click node_db_conn "https://github.com/machadop1407/job-application-tracker/blob/main/lib/db.ts"
click node_board_model "https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/board.ts"
click node_column_model "https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/column.ts"
click node_job_model "https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/job-application.ts"
click node_model_index "https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/index.ts"
click node_navbar "https://github.com/machadop1407/job-application-tracker/blob/main/components/navbar.tsx"
click node_job_card "https://github.com/machadop1407/job-application-tracker/blob/main/components/job-application-card.tsx"
click node_create_dialog "https://github.com/machadop1407/job-application-tracker/blob/main/components/create-job-dialog.tsx"
click node_ui_primitives "https://github.com/machadop1407/job-application-tracker/blob/main/components/ui/button.tsx"

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_app_root,node_home_page,node_sign_in_page,node_sign_up_page,node_dashboard_page toneBlue
class node_proxy_guard,node_auth_route,node_auth_core,node_auth_client,node_board_init,node_boards_hook,node_job_actions toneAmber
class node_db_conn,node_board_model,node_column_model,node_job_model,node_model_index toneMint
class node_kanban_board,node_navbar,node_job_card,node_create_dialog,node_ui_primitives toneRose
```

## Components

### App surfaces

Public pages, authentication pages, and the dashboard workspace.

- [App shell](https://github.com/machadop1407/job-application-tracker/blob/main/app/layout.tsx): Next.js app · Global layout, styles, and top-level page shell. · `app/layout.tsx`
- [Landing page](https://github.com/machadop1407/job-application-tracker/blob/main/app/page.tsx): public page · Marketing/home entry point for unauthenticated visitors. · `app/page.tsx`
- [Sign in](https://github.com/machadop1407/job-application-tracker/blob/main/app/sign-in/page.tsx): auth page · Sign-in screen for existing users. · `app/sign-in/page.tsx`
- [Sign up](https://github.com/machadop1407/job-application-tracker/blob/main/app/sign-up/page.tsx): auth page · Account creation screen for new users. · `app/sign-up/page.tsx`
- [Dashboard](https://github.com/machadop1407/job-application-tracker/blob/main/app/dashboard/page.tsx): server page · Authenticated workspace loader for the personalized Kanban board. · `app/dashboard/page.tsx`

### Runtime flow

Client interaction, server rendering, and route protection.

- [Route guard](https://github.com/machadop1407/job-application-tracker/blob/main/proxy.ts): edge proxy · Protects authenticated routes and blocks unauthorized access. · `proxy.ts`
- [Auth API](https://github.com/machadop1407/job-application-tracker/blob/main/app/api/auth/[...all]/route.ts): route handler · Better Auth endpoint exposed under the app router. · `app/api/auth/[...all]/route.ts`
- [Auth config](https://github.com/machadop1407/job-application-tracker/blob/main/lib/auth/auth.ts): better-auth · Server-side auth setup and session integration. · `lib/auth/auth.ts`
- [Auth client](https://github.com/machadop1407/job-application-tracker/blob/main/lib/auth/auth-client.ts): client auth · Client integration for sign-in, sign-up, and session state. · `lib/auth/auth-client.ts`
- [Seed board](https://github.com/machadop1407/job-application-tracker/blob/main/lib/init-user-board.ts): signup hook · Creates a default board after new account creation. · `lib/init-user-board.ts`
- [Board state](https://github.com/machadop1407/job-application-tracker/blob/main/lib/hooks/useBoards.ts): client hook · Local board state synchronization for drag-and-drop updates. · `lib/hooks/useBoards.ts`
- [Job actions](https://github.com/machadop1407/job-application-tracker/blob/main/lib/actions/job-applications.ts): server actions · Create, update, delete, ownership checks, ordering, and cache refresh. · `lib/actions/job-applications.ts`

### Data layer

Database connection, models, and persistence/mutation logic.

- [DB connect](https://github.com/machadop1407/job-application-tracker/blob/main/lib/db.ts): mongoose db · Central MongoDB connection setup. · `lib/db.ts`
- [Board model](https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/board.ts): mongoose model · Top-level board document in the domain hierarchy. · `lib/models/board.ts`
- [Column model](https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/column.ts): mongoose model · Board columns and their ordering. · `lib/models/column.ts`
- [Job model](https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/job-application.ts): mongoose model · Individual job application records. · `lib/models/job-application.ts`
- [Model index](https://github.com/machadop1407/job-application-tracker/blob/main/lib/models/index.ts): model barrel · Central export surface for domain models. · `lib/models/index.ts`

### Shared UI

Reusable components and styling primitives.

- [Kanban board](https://github.com/machadop1407/job-application-tracker/blob/main/components/kanban-board.tsx): client UI · Drag-and-drop board that renders and updates the job hunt workflow. · `components/kanban-board.tsx`
- [Navbar](https://github.com/machadop1407/job-application-tracker/blob/main/components/navbar.tsx): ui composition · Authenticated navigation shell and sign-out entry. · `components/navbar.tsx`
- [Job card](https://github.com/machadop1407/job-application-tracker/blob/main/components/job-application-card.tsx): board item · Visual representation of a single application on the board. · `components/job-application-card.tsx`
- [Create dialog](https://github.com/machadop1407/job-application-tracker/blob/main/components/create-job-dialog.tsx): ui flow · Dialog for adding new job applications. · `components/create-job-dialog.tsx`
- [UI primitives](https://github.com/machadop1407/job-application-tracker/blob/main/components/ui/button.tsx): Radix ui · Reusable component library for dialogs, forms, buttons, and menus. · `components/ui/button.tsx`

## Connections

- App shell → Landing page: renders · Global app shell wraps the public landing page.
- App shell → Sign in: renders · Global app shell wraps the sign-in page.
- App shell → Sign up: renders · Global app shell wraps the sign-up page.
- App shell → Dashboard: renders · Global app shell wraps the authenticated dashboard.
- Route guard → Dashboard: protects · Blocks unauthenticated access to the dashboard route.
- Auth API → Auth config: implements · Route handler exposes Better Auth behavior.
- Auth client → Auth config: uses · Client calls into the auth system for session and credentials flow.
- Auth config → Seed board: triggers · New signup initializes the default user board.
- Auth config → DB connect: stores in · Auth data and sessions use the shared MongoDB connection.
- Seed board → Board model: creates · Seed hook creates the initial board document.
- Seed board → Column model: creates · Seed hook creates the default column structure.
- Dashboard → DB connect: loads · Server page fetches the authenticated board data.
- Dashboard → Board model: queries · Board is loaded as the primary workspace entity.
- Dashboard → Column model: queries · Populated columns are part of the dashboard load.
- Dashboard → Job model: queries · Job applications are loaded into the board view.
- Dashboard → Kanban board: passes data · Server-rendered board state is handed to the client board UI.
- Kanban board → Board state: syncs state · Drag-and-drop interactions update local board state.
- Kanban board → Job card: composes · Board renders individual application cards.
- Kanban board → Create dialog: opens · Board uses the create dialog for new jobs.
- Kanban board → Job actions: mutates via · Client persists changes through server actions.
- Board state → Job actions: persists · Local reorder and move operations are saved server-side.
- Job actions → DB connect: writes · Server actions persist changes to MongoDB.
- Job actions → Board model: updates · Board ownership and structure are enforced during mutations.
- Job actions → Column model: updates · Column ordering and placement are maintained.
- Job actions → Job model: updates · Job applications are created, edited, moved, and deleted.
- Navbar → Auth client: reads session · Navigation reflects authentication state and sign-out.
- Navbar → UI primitives: uses · Navbar is built from shared UI primitives.
- Job card → UI primitives: uses · Cards rely on shared presentation primitives.
- Create dialog → UI primitives: uses · Dialog and form controls are built from shared primitives.