# axelmendoza05/devhub-web architecture

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

- Interactive diagram: https://gitdiagram.com/axelmendoza05/devhub-web
- Repository: https://github.com/axelmendoza05/devhub-web

## Overview

1. **Project shape**
   - This is a **Next.js App Router** frontend, organized as a workspace/dashboard product rather than a simple marketing site.
   - The repo is mostly presentation and client-side data orchestration; there is no obvious custom backend here. The main architecture is built around route segments, reusable UI components, and feature-specific hooks/services.

2. **Top-level route structure**
   - `app/` is split into two main shells:
     - `app/(auth)` for sign-in/sign-up/SSO callback.
     - `app/(dashboard)` for the authenticated product experience.
   - The dashboard shell contains both the top-level dashboard and a nested **project workspace** under `projects/[projectId]`, with its own layout and child pages.

3. **Workspace/navigation hierarchy**
   - The `projects/[projectId]` subtree is the core domain boundary.
   - It exposes separate sections for `overview`, `activity`, `docs`, `environments`, `resources`, `skills`, `team`, and `settings`.
   - This is a strong indicator that the product is centered on managing a project workspace with multiple functional areas rather than one monolithic page.

4. **Page composition model**
   - Pages are thin route entry points; most real UI is pushed into `components/` and `features/`.
   - Domain pages likely assemble shared layout pieces such as `Navbar`, `PageHeader`, `EmptyState`, and `LoadingState` with domain-specific components like `DocEditor`, `EnvironmentTable`, or `ActivityTimeline`.

5. **Feature/data layer separation**
   - `features/` contains hook-based domain accessors:
     - `useProjects`, `useDocs`, `useEnvironments`, `useResources`, `useSkills`
     - `useWorkspace` for active project context
   - `services/` contains the data-access boundary:
     - `api.ts` plus domain service modules for projects, docs, environments, resources, and skills.
   - This suggests a clean separation: **hooks manage screen-level state**, while **services encapsulate fetching/mutations**.

6. **Client state and data fetching**
   - `providers/QueryProvider.tsx` and `lib/query-client.ts` indicate a centralized query/cache layer, likely for server-state management.
   - `lib/mock-data.ts` suggests the UI can operate against mocked/local data, which is useful for development, demos, or a backend-not-yet-complete mode.
   - `hooks/useWorkspace.ts` is probably the key context bridge that binds the currently selected project/workspace to downstream feature hooks.

7. **Auth and session boundary**
   - Auth is isolated in its own route group and includes `sign-in`, `sign-up`, and `sso-callback`.
   - `proxy.ts` likely acts as a request gate or route guard for authentication/session handling.
   - The architecture suggests authentication is handled externally or through a managed auth flow, with the app receiving the authenticated session before entering the dashboard shell.

8. **Domain modules in the UI**
   - `components/` is organized by business area:
     - `projects`, `docs`, `environments`, `resources`, `skills`, `activity`, `auth`, `layout`
   - Each domain has specialized UI:
     - docs: sidebar + editor
     - environments: table, secret input, add-variable modal
     - projects: create modal, project card
     - skills/resources: library-style cards
     - activity: timeline
   - This points to a component architecture where each domain owns its own visual and interaction patterns.

9. **Shared UI system**
   - `components/ui/` contains the base design primitives: buttons, cards, dialogs, tables, tabs, sheets, tooltips, etc.
   - These are likely the foundation for all higher-level components and enforce consistency across the dashboard.
   - `components.json`, `globals.css`, and `app/layout.tsx` indicate a standardized design-system-driven UI stack.

10. **Theming and app-wide providers**
   - `providers/ThemeProvider.tsx` handles visual mode or theme context across the app.
   - `providers/QueryProvider.tsx` provides shared data-fetching/cache context.
   - `app/layout.tsx` is the composition point for global providers, fonts, and app-wide styling.

11. **Type model and contracts**
   - `types/` defines the domain contracts for `api`, `project`, `doc`, `environment`, `resource`, and `skill`.
   - This strongly suggests the frontend is typed around a clear domain model, with services and hooks consuming those shapes.
   - The architecture diagram should treat these types as the schema boundary between UI logic and data services.

12. **Design/specification artifacts**
   - `docs/` includes API notes, gap analysis, and a routing migration decision record.
   - `docs/superpowers/` contains implementation plans/specs, implying this repo is actively guided by product/design planning docs.
   - `design-system/devhub/MASTER.md` plus the `.claude/skills/ui-ux-pro-max` data look like internal design guidance and generation assets, not runtime code, but they influence how UI is built.

13. **Static reference screens**
   - `stitch-screens/` contains HTML screenshots/pages for portal, dashboard, projects, docs, environments, skills, team, and error states.
   - These appear to be static design references or stitched prototypes used to match the implementation to a target UI.
   - In an architecture diagram, these are best shown as reference assets, not as part of the live runtime path.

14. **Likely runtime flow**
   - User lands on auth pages or is routed through auth guard.
   - After authentication, the dashboard shell loads global providers and shared layout.
   - Workspace selection happens via `useWorkspace` and project routes.
   - Domain pages fetch/cache data through feature hooks and services, then render using shared and domain-specific components.

15. **Overall boundary summary**
   - The key architectural boundaries are:
     - **Route shells**: auth vs. authenticated dashboard
     - **Workspace boundary**: project-specific nested routes and context
     - **Data boundary**: feature hooks ↔ services ↔ types/api
     - **UI boundary**: shared primitives ↔ domain components
   - This repo is best drawn as a typed, componentized Next.js frontend with a project-centric workspace model and a centralized client data layer.

Main entry points: [`app/(dashboard)/projects/[projectId]`](https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)/projects/[projectId]) (Project workspace), [`components`](https://github.com/axelmendoza05/devhub-web/tree/main/components) (Domain components), [`app/layout.tsx`](https://github.com/axelmendoza05/devhub-web/blob/main/app/layout.tsx) (App layout), [`app/(dashboard)`](https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["Route shells"]
  node_app_layout["App layout<br/>nextjs root<br/>[layout.tsx]"]
  node_auth_routes["Auth shell<br/>route group"]
  node_dashboard_shell["Dashboard shell<br/>route group"]
end

subgraph group_workspace["Workspace domain"]
  node_project_workspace["Project workspace<br/>nested routes"]
  node_workspace_sections["Workspace pages<br/>route sections"]
  node_doc_detail["Doc detail<br/>drilldown route<br/>[page.tsx]"]
  node_project_pages["Project pages<br/>dashboard routes<br/>[page.tsx]"]
  node_global_pages["Global pages<br/>dashboard routes<br/>[page.tsx]"]
end

subgraph group_data["Data layer"]
  node_providers["App providers<br/>context layer"]
  node_query_client["Query client<br/>cache setup<br/>[query-client.ts]"]
  node_workspace_hook["Workspace hook<br/>context bridge<br/>[useWorkspace.ts]"]
  node_feature_hooks["Feature hooks<br/>domain accessors"]
  node_services["Services<br/>api boundary"]
  node_types["Domain types<br/>contracts"]
  node_mock_data["Mock data<br/>local dataset<br/>[mock-data.ts]"]
  node_theme_provider["Theme provider<br/>visual context<br/>[ThemeProvider.tsx]"]
end

subgraph group_ui["UI system"]
  node_shared_ui["Shared UI<br/>design system"]
  node_domain_components["Domain components<br/>feature UI"]
  node_page_composition["Page assembly<br/>screen composition"]
end

subgraph group_reference["Reference assets"]
  node_docs_refs["Docs & plans<br/>reference docs"]
  node_design_assets["Design assets<br/>reference assets"]
end

node_app_layout -->|"wraps"| node_providers
node_app_layout -->|"renders"| node_auth_routes
node_app_layout -->|"renders"| node_dashboard_shell
node_dashboard_shell -->|"hosts"| node_project_workspace
node_project_workspace -->|"branches to"| node_workspace_sections
node_workspace_sections -->|"drills into"| node_doc_detail
node_dashboard_shell -->|"includes"| node_global_pages
node_project_workspace -->|"contains"| node_project_pages
node_providers -->|"configures"| node_query_client
node_providers -->|"includes"| node_theme_provider
node_workspace_hook -->|"feeds"| node_feature_hooks
node_feature_hooks -->|"calls"| node_services
node_services -->|"typed by"| node_types
node_services -.->|"falls back to"| node_mock_data
node_domain_components -->|"builds on"| node_shared_ui
node_project_workspace -->|"renders with"| node_domain_components
node_project_workspace -->|"uses"| node_page_composition
node_auth_routes -->|"uses"| node_domain_components
node_docs_refs -.->|"guides"| node_project_workspace
node_design_assets -.->|"informs"| node_domain_components

click node_app_layout "https://github.com/axelmendoza05/devhub-web/blob/main/app/layout.tsx"
click node_auth_routes "https://github.com/axelmendoza05/devhub-web/tree/main/app/(auth)"
click node_dashboard_shell "https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)"
click node_project_workspace "https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)/projects/[projectId]"
click node_doc_detail "https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/projects/[projectId]/docs/[docId]/page.tsx"
click node_project_pages "https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/projects/page.tsx"
click node_global_pages "https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/dashboard/page.tsx"
click node_providers "https://github.com/axelmendoza05/devhub-web/tree/main/providers"
click node_query_client "https://github.com/axelmendoza05/devhub-web/blob/main/lib/query-client.ts"
click node_workspace_hook "https://github.com/axelmendoza05/devhub-web/blob/main/hooks/useWorkspace.ts"
click node_feature_hooks "https://github.com/axelmendoza05/devhub-web/tree/main/features"
click node_services "https://github.com/axelmendoza05/devhub-web/tree/main/services"
click node_types "https://github.com/axelmendoza05/devhub-web/tree/main/types"
click node_shared_ui "https://github.com/axelmendoza05/devhub-web/tree/main/components/ui"
click node_domain_components "https://github.com/axelmendoza05/devhub-web/tree/main/components"
click node_page_composition "https://github.com/axelmendoza05/devhub-web/tree/main/components/shared"
click node_mock_data "https://github.com/axelmendoza05/devhub-web/blob/main/lib/mock-data.ts"
click node_theme_provider "https://github.com/axelmendoza05/devhub-web/blob/main/providers/ThemeProvider.tsx"
click node_docs_refs "https://github.com/axelmendoza05/devhub-web/tree/main/docs"
click node_design_assets "https://github.com/axelmendoza05/devhub-web/tree/main/stitch-screens"

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_layout,node_auth_routes,node_dashboard_shell toneBlue
class node_project_workspace,node_workspace_sections,node_doc_detail,node_project_pages,node_global_pages toneAmber
class node_providers,node_query_client,node_workspace_hook,node_feature_hooks,node_services,node_types,node_mock_data,node_theme_provider toneMint
class node_shared_ui,node_domain_components,node_page_composition toneRose
class node_docs_refs,node_design_assets toneIndigo
```

## Components

### Route shells

Next.js App Router entry points split into auth and authenticated dashboard experiences.

- [App layout](https://github.com/axelmendoza05/devhub-web/blob/main/app/layout.tsx): nextjs root · Global app composition point for providers, fonts, and styling. · `app/layout.tsx`
- [Auth shell](https://github.com/axelmendoza05/devhub-web/tree/main/app/(auth)): route group · Sign-in, sign-up, and SSO callback entry points. · `app/(auth)`
- [Dashboard shell](https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)): route group · Authenticated app layout and top-level dashboard routes. · `app/(dashboard)`

### Workspace domain

Project-centric routes and screens inside the authenticated shell.

- [Project workspace](https://github.com/axelmendoza05/devhub-web/tree/main/app/(dashboard)/projects/[projectId]): nested routes · Project-scoped workspace boundary with nested functional sections. · `app/(dashboard)/projects/[projectId]`
- **Workspace pages**: route sections · Overview, activity, docs, environments, resources, skills, team, and settings pages.
- [Doc detail](https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/projects/[projectId]/docs/[docId]/page.tsx): drilldown route · Dedicated document view inside the workspace docs area. · `app/(dashboard)/projects/[projectId]/docs/[docId]/page.tsx`
- [Project pages](https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/projects/page.tsx): dashboard routes · Top-level project listing plus workspace entry pages. · `app/(dashboard)/projects/page.tsx`
- [Global pages](https://github.com/axelmendoza05/devhub-web/blob/main/app/(dashboard)/dashboard/page.tsx): dashboard routes · Standalone authenticated dashboard pages outside the project workspace. · `app/(dashboard)/dashboard/page.tsx`

### Data layer

Typed client-side state, hooks, and service boundaries.

- [App providers](https://github.com/axelmendoza05/devhub-web/tree/main/providers): context layer · Theme and query client providers shared across the app. · `providers`
- [Query client](https://github.com/axelmendoza05/devhub-web/blob/main/lib/query-client.ts): cache setup · Centralized client-side server-state cache configuration. · `lib/query-client.ts`
- [Workspace hook](https://github.com/axelmendoza05/devhub-web/blob/main/hooks/useWorkspace.ts): context bridge · Active project/workspace selector consumed by downstream features. · `hooks/useWorkspace.ts`
- [Feature hooks](https://github.com/axelmendoza05/devhub-web/tree/main/features): domain accessors · Project, docs, environments, resources, and skills hooks. · `features`
- [Services](https://github.com/axelmendoza05/devhub-web/tree/main/services): api boundary · Typed fetch and mutation services for each domain. · `services`
- [Domain types](https://github.com/axelmendoza05/devhub-web/tree/main/types): contracts · Shared data contracts for API, project, doc, environment, resource, and skill models. · `types`
- [Mock data](https://github.com/axelmendoza05/devhub-web/blob/main/lib/mock-data.ts): local dataset · Local fallback data used for development or demo mode. · `lib/mock-data.ts`
- [Theme provider](https://github.com/axelmendoza05/devhub-web/blob/main/providers/ThemeProvider.tsx): visual context · App-wide theme or color-mode context. · `providers/ThemeProvider.tsx`

### UI system

Shared layout, feature components, and reusable primitives.

- [Shared UI](https://github.com/axelmendoza05/devhub-web/tree/main/components/ui): design system · Reusable layout and low-level interface primitives. · `components/ui`
- [Domain components](https://github.com/axelmendoza05/devhub-web/tree/main/components): feature UI · Specialized components for auth, docs, environments, projects, resources, skills, activity, and layout. · `components`
- [Page assembly](https://github.com/axelmendoza05/devhub-web/tree/main/components/shared): screen composition · Shared page header, loading, and empty states used by route screens. · `components/shared`

### Reference assets

Design docs, planning artifacts, and stitched static screens used to guide implementation.

- [Docs & plans](https://github.com/axelmendoza05/devhub-web/tree/main/docs): reference docs · Architecture notes, decisions, and implementation plans for the frontend scaffold. · `docs`
- [Design assets](https://github.com/axelmendoza05/devhub-web/tree/main/stitch-screens): reference assets · Internal design-system guidance and static stitched reference screens. · `stitch-screens`

## Connections

- App layout → App providers: wraps · Global layout composes shared providers before rendering routes.
- App layout → Auth shell: renders · Root app includes the auth route group.
- App layout → Dashboard shell: renders · Root app includes the authenticated dashboard shell.
- Dashboard shell → Project workspace: hosts · Dashboard shell contains the project workspace boundary.
- Project workspace → Workspace pages: branches to · Workspace routes split into section pages.
- Workspace pages → Doc detail: drills into · Docs section exposes individual document routes.
- Dashboard shell → Global pages: includes · Dashboard shell also contains standalone pages.
- Project workspace → Project pages: contains · Workspace area includes project listing and entry pages.
- App providers → Query client: configures · Query provider relies on the shared query client setup.
- App providers → Theme provider: includes · App-wide provider stack includes theme context.
- Workspace hook → Feature hooks: feeds · Workspace context is consumed by domain hooks.
- Feature hooks → Services: calls · Hooks delegate fetching and mutations to services.
- Services → Domain types: typed by · Service payloads are governed by shared domain contracts.
- Services → Mock data: falls back to · Services can operate against local mock data.
- Domain components → Shared UI: builds on · Feature components are assembled from shared primitives.
- Project workspace → Domain components: renders with · Workspace pages compose domain-specific UI components.
- Project workspace → Page assembly: uses · Routes rely on shared page states and headers.
- Auth shell → Domain components: uses · Auth screens use dedicated auth UI components.
- Docs & plans → Project workspace: guides · Architecture docs describe the workspace routing and product shape.
- Design assets → Domain components: informs · Reference screens and design-system guidance inform UI implementation.