How axelmendoza05/devhub-web works
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: [projectId] Project workspace · components Domain components · layout.tsx App layout · (dashboard) Dashboard shell
Components 21
Route shells
Next.js App Router entry points split into auth and authenticated dashboard experiences.
- App layout · Global app composition point for providers, fonts, and styling.
app/layout.tsx - Auth shell · Sign-in, sign-up, and SSO callback entry points.
app/(auth) - Dashboard shell · Authenticated app layout and top-level dashboard routes.
app/(dashboard)
Workspace domain
Project-centric routes and screens inside the authenticated shell.
- Project workspace · Project-scoped workspace boundary with nested functional sections.
app/(dashboard)/projects/[projectId] - Workspace pages · Overview, activity, docs, environments, resources, skills, team, and settings pages.
- Doc detail · Dedicated document view inside the workspace docs area.
app/(dashboard)/projects/[projectId]/docs/[docId]/page.tsx - Project pages · Top-level project listing plus workspace entry pages.
app/(dashboard)/projects/page.tsx - Global pages · 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 · Theme and query client providers shared across the app.
providers - Query client · Centralized client-side server-state cache configuration.
lib/query-client.ts - Workspace hook · Active project/workspace selector consumed by downstream features.
hooks/useWorkspace.ts - Feature hooks · Project, docs, environments, resources, and skills hooks.
features - Services · Typed fetch and mutation services for each domain.
services - Domain types · Shared data contracts for API, project, doc, environment, resource, and skill models.
types - Mock data · Local fallback data used for development or demo mode.
lib/mock-data.ts - Theme provider · App-wide theme or color-mode context.
providers/ThemeProvider.tsx
UI system
Shared layout, feature components, and reusable primitives.
- Shared UI · Reusable layout and low-level interface primitives.
components/ui - Domain components · Specialized components for auth, docs, environments, projects, resources, skills, activity, and layout.
components - Page assembly · 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 · Architecture notes, decisions, and implementation plans for the frontend scaffold.
docs - Design assets · Internal design-system guidance and static stitched reference screens.
stitch-screens
Connections 20
- 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.