# marwafarid344-lang/morx-team architecture

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

- Interactive diagram: https://gitdiagram.com/marwafarid344-lang/morx-team
- Repository: https://github.com/marwafarid344-lang/morx-team

## Overview

1. **High-level shape**
   - Morx is a **Next.js App Router** application for team task management.
   - The repo is split into two major planes: **UI pages under `app/`** and **server API routes under `app/api/`**.
   - Domain appears centered on **users, teams, projects, tasks, notifications, templates, analytics, and recruitment**.

2. **Frontend presentation layer**
   - Most user-facing screens live in `app/*/page.tsx`, including landing, auth, teams, projects, tasks-related views, templates, talent, reports, settings, and legal pages.
   - Nested layouts such as `app/analytics/layout.tsx` and `app/complete-profile/layout.tsx` suggest route-scoped shells for authenticated or specialized workflows.
   - The app likely relies on **server-rendered pages plus client components** where interactivity is needed.

3. **Component system**
   - Reusable UI is concentrated in `components/`, with a large `components/ui/` base layer that looks like a **design-system / shadcn-style component kit**.
   - Feature components such as `TaskCalendar`, `TaskDocEditor`, `notification-panel`, `report-table`, `template-library`, and `TutorialOverlay` indicate that much of the app’s behavior is composed from reusable widgets rather than page-specific logic.
   - Cross-cutting UX wrappers include auth transition/session sync, theme providers, and tutorial providers.

4. **Authentication and onboarding boundary**
   - Auth is handled through several routes: `app/api/auth/*`, `app/api/login`, `app/auth/callback`, and NextAuth under `app/api/auth/[...nextauth]`.
   - There are dedicated flows for **signup, login, Google OAuth callback, password reset, session fetching, profile completion, and signup completion**.
   - This suggests a multi-step onboarding boundary: public auth pages, an OAuth/session bridge, then protected application routes after profile completion.

5. **Backend API layer**
   - The server API is extensive and organized by domain: `users`, `teams`, `projects`, `tasks`, `comments`, `notifications`, `templates`, `analytics`, `recruitment`, and `ai`.
   - Routes follow REST-like patterns with nested resource actions, for example task assignment, file upload, comment likes, team membership, invite/join flows, and template rating.
   - This API layer is the main boundary where the UI talks to persistent data and business rules.

6. **Core domain model**
   - The main entities are clearly:
     - **User**: profile, stats, notifications, teams, onboarding state
     - **Team**: members, requests, reports, stats, join/invite lifecycle
     - **Project**: project pages plus member management
     - **Task**: assignment, docs, files, comments, status tracking
     - **Template**: create project from template, rating, browsing
     - **Notification**: due-task checks, read state, user notification feed
   - The architecture is organized around these resources rather than around a single monolithic dashboard.

7. **Task collaboration workflow**
   - Tasks are not just records; they support **assignment, comments, likes, documents, and files**.
   - The presence of `app/api/tasks/[taskId]/assign`, `/docs`, `/file`, `/files`, and `comments/like` implies a collaborative workflow where task metadata, discussion, and attachments are all first-class.
   - Public-facing task interactions likely feed into notifications and analytics.

8. **Team and project lifecycle**
   - Teams have join, request, member, report, and stats endpoints, plus team-specific pages for browsing, joining, reports, and settings.
   - Projects are scoped by URL and have member management, indicating a team-centric project container model.
   - `lib/utils/teamUrl.ts` suggests URL slugs are part of the identity and routing model for teams.

9. **Templates and talent marketplace**
   - Templates are a separate subsystem for **bootstrapping projects**, with browse, create-project-from-template, and rating flows.
   - The talent marketplace has its own pages and recruitment APIs for invitations, responses, and talent search.
   - These are adjacent to the core task system but represent discovery/activation flows rather than day-to-day execution.

10. **Analytics and reporting**
   - There are both general analytics routes and team-specific reports/stats pages.
   - Components like `chart-card`, `stats-card`, and `report-table` indicate the reporting layer consumes aggregated API data rather than raw entity views.
   - Analytics likely spans task completion, team activity, and user/team performance indicators referenced in the README.

11. **AI-assisted features**
   - `app/api/ai/generate`, `generate-description`, and `usage` show AI is treated as a service boundary with usage tracking.
   - The UI includes `ai-description-button`, implying AI is used to assist content generation, probably task or project descriptions.
   - `lib/utils/aiUsage.ts` suggests the app tracks consumption or quotas for AI features.

12. **Persistence and infrastructure**
   - The repository uses **Supabase** as its backend data layer, with separate client and server helpers under `lib/supabase/*`.
   - `lib/middleware/auth.ts`, `authCompat.ts`, and `db-helpers.ts` imply server-side access control and database convenience wrappers are centralized.
   - Public uploads are stored under `public/uploads/tasks`, so file handling is at least partly filesystem-backed in the repo, while the app also likely integrates Supabase for authenticated data and profile state.

13. **Shared app state and cross-cutting concerns**
   - Global concerns include **theme**, **toast/notification UI**, **mobile responsiveness**, and **tutorial onboarding**.
   - `contexts/auth-context.tsx`, `theme-provider.tsx`, `color-theme-provider.tsx`, and tutorial context components suggest the app keeps global client state for session-aware UX.
   - These layers sit above the domain features and help coordinate navigation, protected rendering, and user guidance.

14. **What to draw in an architecture diagram**
   - Show the app as three layers: **Next.js pages/components**, **Next.js API routes**, and **Supabase-backed persistence/auth**.
   - Place **auth/onboarding** as an early gate into the protected product.
   - Model **teams → projects → tasks** as the primary domain hierarchy, with side systems for **comments/files/notifications**, **templates**, **recruitment/talent**, **reports/analytics**, and **AI assistance**.

Main entry points: [`app/api/page.tsx`](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/page.tsx) (API Surface), [`lib/supabase/server.ts`](https://github.com/marwafarid344-lang/morx-team/blob/main/lib/supabase/server.ts) (Supabase), [`app/layout.tsx`](https://github.com/marwafarid344-lang/morx-team/blob/main/app/layout.tsx) (Morx), [`app/teams/page.tsx`](https://github.com/marwafarid344-lang/morx-team/blob/main/app/teams/page.tsx) (Workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Router"]
  node_node_public_pages["Public Pages<br/>routes<br/>[page.tsx]"]
  node_node_workspaces["Workspaces<br/>routes<br/>[page.tsx]"]
  node_node_route_shells["Route Shells<br/>layouts<br/>[layout.tsx]"]
end

subgraph group_group_api["API Routes"]
  node_node_api_surface["API Surface<br/>server routes<br/>[page.tsx]"]
  node_node_auth_api["Auth API<br/>auth routes<br/>[route.ts]"]
  node_node_users_api["Users API<br/>user routes<br/>[route.ts]"]
  node_node_teams_api["Teams API<br/>team routes<br/>[route.ts]"]
  node_node_projects_api["Projects API<br/>project routes<br/>[route.ts]"]
  node_node_tasks_api["Tasks API<br/>task routes<br/>[route.ts]"]
  node_node_templates_api["Templates API<br/>template routes<br/>[route.ts]"]
  node_node_recruitment_api["Recruitment API<br/>talent routes<br/>[route.ts]"]
  node_node_analytics_api["Analytics API<br/>report routes<br/>[route.ts]"]
  node_node_ai_api["AI API<br/>ai routes<br/>[route.ts]"]
end

subgraph group_group_shared["Shared Client"]
  node_node_ui_kit["UI Kit<br/>design system<br/>[button.tsx]"]
  node_node_feature_widgets["Feature Widgets<br/>feature components<br/>[TaskCalendar.tsx]"]
  node_node_crosscutting["App State<br/>providers<br/>[auth-context.tsx]"]
end

subgraph group_group_infra["Data Layer"]
  node_node_supabase[("Supabase<br/>backend service<br/>[server.ts]")]
  node_node_server_helpers["Server Helpers<br/>middleware/utils<br/>[auth.ts]"]
  node_node_assets["Upload Assets<br/>files<br/>[README.md]"]
end

node_node_root["Morx<br/>Next.js app<br/>[layout.tsx]"]

node_node_root -->|"renders"| node_node_public_pages
node_node_root -->|"hosts"| node_node_workspaces
node_node_root -->|"scopes"| node_node_route_shells
node_node_public_pages -->|"uses"| node_node_crosscutting
node_node_workspaces -->|"composes"| node_node_feature_widgets
node_node_workspaces -->|"builds on"| node_node_ui_kit
node_node_api_surface -->|"contains"| node_node_auth_api
node_node_api_surface -->|"contains"| node_node_users_api
node_node_api_surface -->|"contains"| node_node_teams_api
node_node_api_surface -->|"contains"| node_node_projects_api
node_node_api_surface -->|"contains"| node_node_tasks_api
node_node_api_surface -->|"contains"| node_node_templates_api
node_node_api_surface -->|"contains"| node_node_recruitment_api
node_node_api_surface -->|"contains"| node_node_analytics_api
node_node_api_surface -->|"contains"| node_node_ai_api
node_node_auth_api -->|"authenticates"| node_node_supabase
node_node_users_api -->|"reads/writes"| node_node_supabase
node_node_teams_api -->|"reads/writes"| node_node_supabase
node_node_projects_api -->|"reads/writes"| node_node_supabase
node_node_tasks_api -->|"reads/writes"| node_node_supabase
node_node_templates_api -->|"reads/writes"| node_node_supabase
node_node_recruitment_api -->|"reads/writes"| node_node_supabase
node_node_analytics_api -->|"aggregates"| node_node_supabase
node_node_ai_api -->|"tracks usage"| node_node_supabase
node_node_feature_widgets -->|"uploads"| node_node_assets
node_node_server_helpers -->|"supports"| node_node_supabase
node_node_crosscutting -->|"coordinates"| node_node_auth_api
node_node_crosscutting -->|"extends"| node_node_feature_widgets

click node_node_root "https://github.com/marwafarid344-lang/morx-team/blob/main/app/layout.tsx"
click node_node_public_pages "https://github.com/marwafarid344-lang/morx-team/blob/main/app/page.tsx"
click node_node_workspaces "https://github.com/marwafarid344-lang/morx-team/blob/main/app/teams/page.tsx"
click node_node_route_shells "https://github.com/marwafarid344-lang/morx-team/blob/main/app/analytics/layout.tsx"
click node_node_api_surface "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/page.tsx"
click node_node_auth_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_node_users_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/users/route.ts"
click node_node_teams_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/teams/route.ts"
click node_node_projects_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/projects/route.ts"
click node_node_tasks_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/tasks/route.ts"
click node_node_templates_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/templates/route.ts"
click node_node_recruitment_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/recruitment/invitations/route.ts"
click node_node_analytics_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/analytics/route.ts"
click node_node_ai_api "https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/ai/generate/route.ts"
click node_node_ui_kit "https://github.com/marwafarid344-lang/morx-team/blob/main/components/ui/button.tsx"
click node_node_feature_widgets "https://github.com/marwafarid344-lang/morx-team/blob/main/components/TaskCalendar.tsx"
click node_node_crosscutting "https://github.com/marwafarid344-lang/morx-team/blob/main/contexts/auth-context.tsx"
click node_node_supabase "https://github.com/marwafarid344-lang/morx-team/blob/main/lib/supabase/server.ts"
click node_node_server_helpers "https://github.com/marwafarid344-lang/morx-team/blob/main/lib/middleware/auth.ts"
click node_node_assets "https://github.com/marwafarid344-lang/morx-team/blob/main/public/uploads/tasks/README.md"

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_node_public_pages,node_node_workspaces,node_node_route_shells toneBlue
class node_node_api_surface,node_node_auth_api,node_node_users_api,node_node_teams_api,node_node_projects_api,node_node_tasks_api,node_node_templates_api,node_node_recruitment_api,node_node_analytics_api,node_node_ai_api toneAmber
class node_node_ui_kit,node_node_feature_widgets,node_node_crosscutting toneMint
class node_node_supabase,node_node_server_helpers,node_node_assets toneRose
class node_node_root toneNeutral
```

## Components

### App Router

User-facing pages and route-scoped shells

- [Public Pages](https://github.com/marwafarid344-lang/morx-team/blob/main/app/page.tsx): routes · Landing, docs, pricing, legal, and auth entry points · `app/page.tsx`
- [Workspaces](https://github.com/marwafarid344-lang/morx-team/blob/main/app/teams/page.tsx): routes · Teams, projects, tasks, templates, talent, reports, and settings · `app/teams/page.tsx`
- [Route Shells](https://github.com/marwafarid344-lang/morx-team/blob/main/app/analytics/layout.tsx): layouts · Analytics and onboarding-specific layouts and completion flows · `app/analytics/layout.tsx`

### API Routes

Domain APIs and auth bridges

- [API Surface](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/page.tsx): server routes · Next.js route handlers for core domains · `app/api/page.tsx`
- [Auth API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/auth/[...nextauth]/route.ts): auth routes · Signup, login, session, OAuth callback, and profile completion · `app/api/auth/[...nextauth]/route.ts`
- [Users API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/users/route.ts): user routes · Profiles, stats, teams, notifications, and onboarding actions · `app/api/users/route.ts`
- [Teams API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/teams/route.ts): team routes · Team lifecycle, join, members, requests, reports, and stats · `app/api/teams/route.ts`
- [Projects API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/projects/route.ts): project routes · Project lookup and member management by URL · `app/api/projects/route.ts`
- [Tasks API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/tasks/route.ts): task routes · Tasks, assignment, docs, files, comments, and likes · `app/api/tasks/route.ts`
- [Templates API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/templates/route.ts): template routes · Browse, rate, and create projects from templates · `app/api/templates/route.ts`
- [Recruitment API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/recruitment/invitations/route.ts): talent routes · Invitations, responses, and talent search · `app/api/recruitment/invitations/route.ts`
- [Analytics API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/analytics/route.ts): report routes · Aggregated metrics and reporting data · `app/api/analytics/route.ts`
- [AI API](https://github.com/marwafarid344-lang/morx-team/blob/main/app/api/ai/generate/route.ts): ai routes · Generation and usage tracking · `app/api/ai/generate/route.ts`

### Shared Client

Reusable components, providers, and hooks

- [UI Kit](https://github.com/marwafarid344-lang/morx-team/blob/main/components/ui/button.tsx): design system · Base shadcn-style UI primitives · `components/ui/button.tsx`
- [Feature Widgets](https://github.com/marwafarid344-lang/morx-team/blob/main/components/TaskCalendar.tsx): feature components · Task calendar, doc editor, reports, templates, and notifications · `components/TaskCalendar.tsx`
- [App State](https://github.com/marwafarid344-lang/morx-team/blob/main/contexts/auth-context.tsx): providers · Auth sync, theme, tutorial, mobile, and toast state · `contexts/auth-context.tsx`

### Data Layer

Supabase and repository infrastructure

- [Supabase](https://github.com/marwafarid344-lang/morx-team/blob/main/lib/supabase/server.ts): backend service · Server and client persistence/auth helpers · `lib/supabase/server.ts`
- [Server Helpers](https://github.com/marwafarid344-lang/morx-team/blob/main/lib/middleware/auth.ts): middleware/utils · Auth middleware, db helpers, URL helpers, and usage utilities · `lib/middleware/auth.ts`
- [Upload Assets](https://github.com/marwafarid344-lang/morx-team/blob/main/public/uploads/tasks/README.md): files · Public task uploads and static assets · `public/uploads/tasks/README.md`

### Other components

- [Morx](https://github.com/marwafarid344-lang/morx-team/blob/main/app/layout.tsx): Next.js app · Team task management platform · `app/layout.tsx`

## Connections

- Morx → Public Pages: renders · App shell serves public and marketing pages
- Morx → Workspaces: hosts · Primary authenticated product areas
- Morx → Route Shells: scopes · Route-specific shells for onboarding and analytics
- Public Pages → App State: uses · Shared providers and UX wrappers
- Workspaces → Feature Widgets: composes · Feature-rich screens assembled from reusable widgets
- Workspaces → UI Kit: builds on · Workspace pages use the shared component base
- API Surface → Auth API: contains · API layer includes the authentication boundary
- API Surface → Users API: contains · User profile and onboarding APIs
- API Surface → Teams API: contains · Team lifecycle APIs
- API Surface → Projects API: contains · Project APIs
- API Surface → Tasks API: contains · Task collaboration APIs
- API Surface → Templates API: contains · Template APIs
- API Surface → Recruitment API: contains · Talent and invitation APIs
- API Surface → Analytics API: contains · Metrics and reporting APIs
- API Surface → AI API: contains · AI generation and usage APIs
- Auth API → Supabase: authenticates · Session and OAuth state bridge to backend
- Users API → Supabase: reads/writes · Profiles, stats, notifications, onboarding
- Teams API → Supabase: reads/writes · Teams, members, requests, reports, stats
- Projects API → Supabase: reads/writes · Project and membership persistence
- Tasks API → Supabase: reads/writes · Tasks, comments, docs, files, assignments
- Templates API → Supabase: reads/writes · Template catalog and project creation
- Recruitment API → Supabase: reads/writes · Talent search and invite workflows
- Analytics API → Supabase: aggregates · Reporting data sourced from backend records
- AI API → Supabase: tracks usage · AI generation and quota bookkeeping
- Feature Widgets → Upload Assets: uploads · Task attachments and other stored files
- Server Helpers → Supabase: supports · Common server access and data helpers
- App State → Auth API: coordinates · Session sync and protected rendering
- App State → Feature Widgets: extends · Tutorial, theme, and toast behaviors
