# ranjeetj06/management architecture

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

- Interactive diagram: https://gitdiagram.com/ranjeetj06/management
- Repository: https://github.com/ranjeetj06/management

## Overview

1. **Overall shape**
   - This is a **Next.js 14 App Router** application backed by **Supabase**.
   - The app is organized around a **multi-workspace CRM/business diary**: users sign in, join or create a workspace, and then operate only on data belonging to that organization.

2. **Top-level route boundaries**
   - `src/app/(auth)` contains the **public authentication flow**: login and signup.
   - `src/app/onboarding` handles **first-time workspace setup** after signup.
   - `src/app/(app)` is the **authenticated application shell** with the main sidebar/layout and all business modules.

3. **Authenticated application shell**
   - `src/app/(app)/layout.tsx` is the structural boundary for the logged-in area.
   - It likely combines auth gating, navigation, and workspace context so all child pages inherit the same shell.
   - This shell hosts the operational modules: dashboard, contacts, interactions, deals, leads, pipeline, accounts, tickets, tasks, team, settings, reports, and more.

4. **Core business domains**
   - The central data domains are:
     - **Contacts**: suppliers, buyers, partners
     - **Interactions**: dated diary entries with location, summary, follow-up, and line items
     - **Deals**: firm orders with payment status
     - **Categories**: product taxonomy
   - Supporting operational modules include **leads**, **accounts**, **tickets**, **tasks**, **team**, **communications**, **documents**, **knowledge**, **calendar**, and **reports**.

5. **Entity lifecycle routes**
   - Most primary entities use a consistent CRUD pattern under `/(app)/<entity>`:
     - list page
     - `new` page
     - `[id]` detail page
     - `[id]/edit` page
   - This pattern exists for contacts, interactions, deals, accounts, knowledge articles, tickets, and leads, which makes the architecture page-driven and domain-centric rather than API-centric.

6. **Specialized workspace views**
   - Some modules are not simple CRUD pages and act as **workspace dashboards or boards**:
     - `leads-board.tsx`
     - `pipeline-board.tsx`
     - `tasks-manager.tsx`
     - `team-manager.tsx`
     - `categories-manager.tsx`
   - These suggest more interactive, stateful views for organizing records rather than just editing them.

7. **Component layer**
   - `src/components` holds reusable UI and domain forms.
   - There are generic UI primitives in `components/ui` and domain-specific forms/managers such as `contact-form`, `deal-form`, `interaction-form`, `lead-form`, `ticket-form`, `automation-manager`, `communications-manager`, `documents-manager`, `integrations-manager`, and `email-templates-manager`.
   - This separation implies the app is built from shared primitives plus domain-specific screens.

8. **Data access and business logic**
   - `src/lib` contains the main non-UI logic:
     - Supabase client/server/admin setup
     - org and member helpers
     - active organization resolution
     - CSV export helpers
     - reporting and activity helpers
     - lead/ticket-related utilities
   - `src/lib/types.ts` likely provides schema-derived TypeScript types that unify client and server code around the Supabase data model.

9. **Supabase as the backend boundary**
   - `supabase/migrations` defines the actual backend schema and permissions model.
   - The data model centers on:
     - `organizations`
     - `members`
     - `invitations`
     - `categories`
     - `contacts`
     - `interactions` and `interaction_items`
     - `deals` and `deal_items`
   - Row Level Security is a core boundary: each workspace only sees its own rows.

10. **Authentication and session flow**
   - Auth supports **email/password**, **magic link**, and **Google sign-in**.
   - `src/app/auth/callback/route.ts` is the landing point for OAuth and magic-link callbacks.
   - `src/middleware.ts` and `src/lib/supabase/middleware.ts` handle session refresh/cookie management so authenticated navigation stays consistent.

11. **Workspace and team management**
   - Workspace membership is first-class: users can **create a workspace**, **switch workspaces**, and **leave a workspace** via API routes.
   - Team invites are handled through dedicated routes under `src/app/api/invitations` and `src/app/api/invite`.
   - The README indicates invitation acceptance is tied to signup and database triggers, so team onboarding is partially automated at the backend layer.

12. **API surface**
   - The API routes are narrow and support supporting operations rather than general CRUD:
     - CSV export for contacts, deals, interactions, leads, accounts, reports
     - invitation accept/decline
     - invite creation
     - workspace switch/leave
   - This means most business data interaction is likely done through server components/forms and Supabase directly, with APIs reserved for cross-cutting actions.

13. **External services and deployment**
   - The app depends materially on **Supabase** for auth, database, RLS, and invitation/workspace behavior.
   - The README describes deployment on **Vercel**, with environment variables for Supabase URL, anon key, and site URL.
   - Google OAuth is optional but affects the auth boundary when enabled.

14. **What an architecture diagram should emphasize**
   - Show three main zones:
     - **Public auth/onboarding**
     - **Authenticated workspace app**
     - **Supabase backend**
   - Then connect the app to Supabase through:
     - auth/session handling
     - organization-scoped data access
     - invite/workspace APIs
     - export/reporting paths
   - The app is not a single monolith of screens; it is a **workspace-scoped CRUD + board UI over a Supabase schema with RLS**.

Main entry points: [`src/app/(app)/layout.tsx`](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/layout.tsx) (App shell), [`src/components/contact-form.tsx`](https://github.com/ranjeetj06/management/blob/master/src/components/contact-form.tsx) (Domain forms), [`src/lib/supabase/server.ts`](https://github.com/ranjeetj06/management/blob/master/src/lib/supabase/server.ts) (Supabase helpers), [`supabase/migrations/0001_init.sql`](https://github.com/ranjeetj06/management/blob/master/supabase/migrations/0001_init.sql) (Schema & RLS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public auth"]
  node_root(("Home<br/>marketing entry<br/>[page.tsx]"))
  node_auth_layout["Auth shell<br/>auth layout<br/>[layout.tsx]"]
  node_login["Login<br/>auth screen<br/>[page.tsx]"]
  node_signup["Signup<br/>auth screen<br/>[page.tsx]"]
  node_callback["Auth callback<br/>oauth handler<br/>[route.ts]"]
  node_onboarding["Onboarding<br/>workspace setup<br/>[page.tsx]"]
end

subgraph group_app["Workspace app"]
  node_app_layout["App shell<br/>workspace layout<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>overview page<br/>[page.tsx]"]
  node_contacts["Contacts<br/>CRM CRUD<br/>[page.tsx]"]
  node_interactions["Interactions<br/>diary CRUD<br/>[page.tsx]"]
  node_deals["Deals<br/>orders CRUD<br/>[page.tsx]"]
  node_leads["Leads<br/>pipeline board<br/>[leads-board.tsx]"]
  node_pipeline["Pipeline<br/>kanban board<br/>[pipeline-board.tsx]"]
  node_tasks["Tasks<br/>work manager<br/>[tasks-manager.tsx]"]
  node_team["Team<br/>member manager<br/>[team-manager.tsx]"]
  node_settings["Settings<br/>workspace config<br/>[page.tsx]"]
  node_categories["Categories<br/>taxonomy manager"]
  node_communications["Communications<br/>messaging hub<br/>[page.tsx]"]
  node_documents["Documents<br/>document hub<br/>[page.tsx]"]
  node_knowledge["Knowledge<br/>kb CRUD<br/>[page.tsx]"]
  node_tickets["Tickets<br/>support CRUD<br/>[page.tsx]"]
  node_reports["Reports<br/>analytics<br/>[page.tsx]"]
  node_app_api["API actions<br/>route handlers<br/>[route.ts]"]
  node_forms["Domain forms<br/>ui forms<br/>[contact-form.tsx]"]
end

subgraph group_data["Data layer"]
  node_supabase_lib["Supabase helpers<br/>server/client helpers<br/>[server.ts]"]
  node_types["Schema types<br/>typed model<br/>[types.ts]"]
  node_migrations[("Schema & RLS<br/>postgres migrations<br/>[0001_init.sql]")]
end

node_root -->|"routes to"| node_auth_layout
node_auth_layout -->|"contains"| node_login
node_auth_layout -->|"contains"| node_signup
node_login -->|"auth returns via"| node_callback
node_signup -->|"continues to"| node_onboarding
node_callback -->|"session handled by"| node_supabase_lib
node_onboarding -->|"creates workspace in"| node_migrations
node_app_layout -->|"hosts"| node_dashboard
node_app_layout -->|"hosts"| node_contacts
node_app_layout -->|"hosts"| node_interactions
node_app_layout -->|"hosts"| node_deals
node_app_layout -->|"hosts"| node_leads
node_app_layout -->|"hosts"| node_pipeline
node_app_layout -->|"hosts"| node_tasks
node_app_layout -->|"hosts"| node_team
node_app_layout -->|"hosts"| node_settings
node_app_layout -->|"hosts"| node_categories
node_app_layout -->|"hosts"| node_communications
node_app_layout -->|"hosts"| node_documents
node_app_layout -->|"hosts"| node_knowledge
node_app_layout -->|"hosts"| node_tickets
node_app_layout -->|"hosts"| node_reports
node_contacts -->|"uses"| node_forms
node_interactions -->|"uses"| node_forms
node_deals -->|"uses"| node_forms
node_leads -->|"uses"| node_forms
node_tickets -->|"uses"| node_forms
node_app_api -->|"delegates to"| node_supabase_lib
node_app_api -->|"enforces"| node_migrations
node_supabase_lib -->|"shares model"| node_types
node_supabase_lib -->|"reads/writes"| node_migrations
node_types -->|"derived from"| node_migrations

click node_root "https://github.com/ranjeetj06/management/blob/master/src/app/page.tsx"
click node_auth_layout "https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/layout.tsx"
click node_login "https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/login/page.tsx"
click node_signup "https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/signup/page.tsx"
click node_callback "https://github.com/ranjeetj06/management/blob/master/src/app/auth/callback/route.ts"
click node_onboarding "https://github.com/ranjeetj06/management/blob/master/src/app/onboarding/page.tsx"
click node_app_layout "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/layout.tsx"
click node_dashboard "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/dashboard/page.tsx"
click node_contacts "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/contacts/page.tsx"
click node_interactions "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/interactions/page.tsx"
click node_deals "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/deals/page.tsx"
click node_leads "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/leads/leads-board.tsx"
click node_pipeline "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/pipeline/pipeline-board.tsx"
click node_tasks "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/tasks/tasks-manager.tsx"
click node_team "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/team/team-manager.tsx"
click node_settings "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/settings/page.tsx"
click node_categories "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/categories/categories-manager.tsx"
click node_communications "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/communications/page.tsx"
click node_documents "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/documents/page.tsx"
click node_knowledge "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/knowledge/page.tsx"
click node_tickets "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/tickets/page.tsx"
click node_reports "https://github.com/ranjeetj06/management/blob/master/src/app/(app)/reports/page.tsx"
click node_app_api "https://github.com/ranjeetj06/management/blob/master/src/app/api/export/contacts/route.ts"
click node_forms "https://github.com/ranjeetj06/management/blob/master/src/components/contact-form.tsx"
click node_supabase_lib "https://github.com/ranjeetj06/management/blob/master/src/lib/supabase/server.ts"
click node_types "https://github.com/ranjeetj06/management/blob/master/src/lib/types.ts"
click node_migrations "https://github.com/ranjeetj06/management/blob/master/supabase/migrations/0001_init.sql"

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_layout,node_login,node_signup,node_callback,node_onboarding toneBlue
class node_app_layout,node_dashboard,node_contacts,node_interactions,node_deals,node_leads,node_pipeline,node_tasks,node_team,node_settings,node_categories,node_communications,node_documents,node_knowledge,node_tickets,node_reports,node_app_api,node_forms toneAmber
class node_supabase_lib,node_types,node_migrations toneMint
```

## Components

### Public auth

Sign-in, signup, callback, and first-run workspace setup.

- [Home](https://github.com/ranjeetj06/management/blob/master/src/app/page.tsx): marketing entry · Public landing route that funnels users into auth or onboarding. · `src/app/page.tsx`
- [Auth shell](https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/layout.tsx): auth layout · Shared layout for login and signup routes. · `src/app/(auth)/layout.tsx`
- [Login](https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/login/page.tsx): auth screen · Email/password, magic-link, and Google sign-in entry. · `src/app/(auth)/login/page.tsx`
- [Signup](https://github.com/ranjeetj06/management/blob/master/src/app/(auth)/signup/page.tsx): auth screen · Account creation flow that leads into workspace onboarding. · `src/app/(auth)/signup/page.tsx`
- [Auth callback](https://github.com/ranjeetj06/management/blob/master/src/app/auth/callback/route.ts): oauth handler · Landing route for OAuth and magic-link callbacks. · `src/app/auth/callback/route.ts`
- [Onboarding](https://github.com/ranjeetj06/management/blob/master/src/app/onboarding/page.tsx): workspace setup · First-run workspace setup after signup. · `src/app/onboarding/page.tsx`

### Workspace app

Authenticated App Router shell and business modules.

- [App shell](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/layout.tsx): workspace layout · Authenticated workspace boundary that wraps all business modules. · `src/app/(app)/layout.tsx`
- [Dashboard](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/dashboard/page.tsx): overview page · Workspace landing page and operational summary. · `src/app/(app)/dashboard/page.tsx`
- [Contacts](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/contacts/page.tsx): CRM CRUD · Workspace-scoped contact records with list/new/detail/edit routes. · `src/app/(app)/contacts/page.tsx`
- [Interactions](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/interactions/page.tsx): diary CRUD · Diary-style interaction records with items and follow-up context. · `src/app/(app)/interactions/page.tsx`
- [Deals](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/deals/page.tsx): orders CRUD · Firm-order records with payment and line-item structure. · `src/app/(app)/deals/page.tsx`
- [Leads](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/leads/leads-board.tsx): pipeline board · Lead management with a board-oriented workspace view. · `src/app/(app)/leads/leads-board.tsx`
- [Pipeline](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/pipeline/pipeline-board.tsx): kanban board · Deal pipeline board for moving opportunities through stages. · `src/app/(app)/pipeline/pipeline-board.tsx`
- [Tasks](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/tasks/tasks-manager.tsx): work manager · Stateful task management workspace. · `src/app/(app)/tasks/tasks-manager.tsx`
- [Team](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/team/team-manager.tsx): member manager · Team and membership management workspace. · `src/app/(app)/team/team-manager.tsx`
- [Settings](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/settings/page.tsx): workspace config · Workspace settings hub including automation, integrations, and roles. · `src/app/(app)/settings/page.tsx`
- [Categories](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/categories/categories-manager.tsx): taxonomy manager · Product and classification taxonomy management. · `src/app/(app)/categories/categories-manager.tsx`
- [Communications](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/communications/page.tsx): messaging hub · Communication tools and email templates. · `src/app/(app)/communications/page.tsx`
- [Documents](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/documents/page.tsx): document hub · Workspace document management area. · `src/app/(app)/documents/page.tsx`
- [Knowledge](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/knowledge/page.tsx): kb CRUD · Knowledge base articles with list/new/detail/edit routes. · `src/app/(app)/knowledge/page.tsx`
- [Tickets](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/tickets/page.tsx): support CRUD · Support ticket records with a dedicated workspace view. · `src/app/(app)/tickets/page.tsx`
- [Reports](https://github.com/ranjeetj06/management/blob/master/src/app/(app)/reports/page.tsx): analytics · Workspace reporting and export-oriented view. · `src/app/(app)/reports/page.tsx`
- [API actions](https://github.com/ranjeetj06/management/blob/master/src/app/api/export/contacts/route.ts): route handlers · Narrow API surface for exports, invitations, and workspace switching. · `src/app/api/export/contacts/route.ts`
- [Domain forms](https://github.com/ranjeetj06/management/blob/master/src/components/contact-form.tsx): ui forms · Reusable domain forms and managers used by CRUD pages and workspace tools. · `src/components/contact-form.tsx`

### Data layer

Shared server/client helpers and Supabase backend schema.

- [Supabase helpers](https://github.com/ranjeetj06/management/blob/master/src/lib/supabase/server.ts): server/client helpers · Client, server, middleware, org, member, report, CSV, and activity helpers. · `src/lib/supabase/server.ts`
- [Schema types](https://github.com/ranjeetj06/management/blob/master/src/lib/types.ts): typed model · Shared TypeScript types derived from the backend schema. · `src/lib/types.ts`
- [Schema & RLS](https://github.com/ranjeetj06/management/blob/master/supabase/migrations/0001_init.sql): postgres migrations · Workspace schema, permissions, invitations, and row-level security rules. · `supabase/migrations/0001_init.sql`

## Connections

- Home → Auth shell: routes to · Public users enter the auth shell.
- Auth shell → Login: contains · Login is a child route of the auth shell.
- Auth shell → Signup: contains · Signup is a child route of the auth shell.
- Login → Auth callback: auth returns via · OAuth and magic-link completion lands in the callback route.
- Signup → Onboarding: continues to · New users are guided into workspace setup.
- Auth callback → Supabase helpers: session handled by · Callback processing relies on Supabase auth/session helpers.
- Onboarding → Schema & RLS: creates workspace in · First-run setup persists workspace state in the backend schema.
- App shell → Dashboard: hosts · The authenticated shell wraps the main dashboard.
- App shell → Contacts: hosts · Contacts live inside the workspace shell.
- App shell → Interactions: hosts · Interactions live inside the workspace shell.
- App shell → Deals: hosts · Deals live inside the workspace shell.
- App shell → Leads: hosts · Leads board lives inside the workspace shell.
- App shell → Pipeline: hosts · Pipeline board lives inside the workspace shell.
- App shell → Tasks: hosts · Tasks manager lives inside the workspace shell.
- App shell → Team: hosts · Team manager lives inside the workspace shell.
- App shell → Settings: hosts · Settings pages live inside the workspace shell.
- App shell → Categories: hosts · Categories manager lives inside the workspace shell.
- App shell → Communications: hosts · Communications tools live inside the workspace shell.
- App shell → Documents: hosts · Document management lives inside the workspace shell.
- App shell → Knowledge: hosts · Knowledge articles live inside the workspace shell.
- App shell → Tickets: hosts · Support tickets live inside the workspace shell.
- App shell → Reports: hosts · Reporting lives inside the workspace shell.
- Contacts → Domain forms: uses · CRUD pages reuse domain forms and primitives.
- Interactions → Domain forms: uses · Interaction pages reuse domain forms and primitives.
- Deals → Domain forms: uses · Deal pages reuse domain forms and primitives.
- Leads → Domain forms: uses · Lead pages and boards reuse domain forms and managers.
- Tickets → Domain forms: uses · Ticket pages reuse ticket-specific forms and workspace UI.
- API actions → Supabase helpers: delegates to · API routes use shared server helpers and workspace resolution.
- API actions → Schema & RLS: enforces · Invite, export, and workspace actions rely on the backend schema and permissions.
- Supabase helpers → Schema types: shares model · Helpers and UI share schema-derived types.
- Supabase helpers → Schema & RLS: reads/writes · Server helpers operate against the Supabase schema and RLS boundary.
- Schema types → Schema & RLS: derived from · Types mirror the underlying database model.
