# thek1d21/gago-smartech-carrers architecture

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

- Interactive diagram: https://gitdiagram.com/thek1d21/gago-smartech-carrers
- Repository: https://github.com/thek1d21/gago-smartech-carrers

## Overview

1. **Overall shape**
   This is a **Next.js App Router** application built as a colocation-heavy admin template. The top-level split is between:
   - `src/app/(external)` for public-facing pages
   - `src/app/(main)` for the authenticated/admin experience

2. **Route and layout structure**
   The main UI is organized around route groups and nested layouts:
   - `src/app/layout.tsx` and `src/app/globals.css` set the global shell
   - `src/app/(main)/dashboard/layout.tsx`, `chat/layout.tsx`, `mail/layout.tsx`, and auth layouts define section-specific frames
   - The dashboard has many sub-routes, including modern dashboards, legacy dashboard variants, admin CRUD screens, employee views, and utility pages like unauthorized and not-found

3. **Primary product domains**
   The repository is not a single-purpose dashboard; it models a **career/talent platform** inside an admin shell. The main business domains are:
   - employees
   - career plans
   - talent frameworks
   - certifications, skills, review cycles, and settings
   - action queue and reports
   - user/role administration
   These are surfaced through pages under `src/app/(main)/dashboard/...` and the supporting logic in `src/features/...`.

4. **Feature-layer architecture**
   Business logic is separated from route components into `src/features`. This layer holds:
   - domain models, schemas, and query helpers
   - management/service modules for admin and employee workflows
   - analytics/reporting and talent-mapping logic
   - import jobs and action-queue logic
   The route folders mostly assemble UI and call into these feature modules.

5. **UI composition**
   Shared presentation is handled by:
   - `src/components/ui/*` for the shadcn-style component library
   - reusable widgets such as `date-range-picker` and `simple-icon`
   - per-page dashboard widgets colocated next to the page they support
   Most dashboard pages are composed from cards, tables, toolbars, and charts, with TanStack Table-style table components appearing in several sections.

6. **Data and state flow**
   The app uses a mix of:
   - static/mock data files colocated with components
   - domain logic in `src/features`
   - server actions for mutations
   - client-side state for UI preferences and interactive dashboards
   The flow is typically: page route → feature logic or server action → form/table component → rendered dashboard/admin view.

7. **Auth and access control**
   Authentication and authorization are first-class concerns:
   - auth screens live under `src/app/(main)/auth`
   - access control helpers live in `src/lib/auth`
   - route policy and role definitions are centralized there
   - an `unauthorized` route is provided for denied access
   This suggests the app enforces permissions at both the route/UI level and in backend-oriented logic.

8. **Backend and persistence**
   The presence of `src/lib/supabase` plus `supabase/migrations`, `supabase/seed.sql`, and QA SQL scripts shows that **Supabase is the persistence/backend boundary**. The repo includes:
   - schema migrations for core platform tables
   - seed data and demo/pilot readiness checks
   - database-level authorization/governance documentation
   This means the app is wired to a real database-backed backend rather than being purely static.

9. **Mutation and validation boundaries**
   Mutating workflows are concentrated in route-local `actions.ts` files and shared server-action helpers in `src/server/server-actions.ts`. Validation is handled with Zod schemas in `src/features/*/*-schema.ts` and related management schema files. That gives the codebase a clear boundary between:
   - input validation
   - server mutation
   - UI forms

10. **User preferences and theming**
   The app has a dedicated preference subsystem:
   - `src/stores/preferences`
   - `src/lib/preferences`
   - `src/lib/local-storage.client.ts`
   - theme presets in `src/styles/presets`
   This supports layout controls, theme switching, and persistent UI settings across sessions.

11. **Navigation and shell**
   The left-nav/admin shell is its own subsystem:
   - sidebar config and user navigation live in `src/navigation/sidebar`
   - shell components live under `src/app/(main)/dashboard/_components/sidebar`
   This is the frame that ties together the many dashboard modules and is likely a key architectural box in any diagram.

12. **Feature clusters worth diagramming**
   Several modules are architecturally distinct and likely deserve separate boxes:
   - **Employee management**: profile, assignments, career plans, imports
   - **Admin governance**: skills, certifications, frameworks, review cycles, settings, templates, audit
   - **Talent analytics**: skill matrix, promotion pipeline, talent map, certification coverage
   - **Collaboration tools**: chat, mail, kanban, invoice, logistics, CRM, finance, analytics
   These are mostly separate route surfaces sharing the same app shell and component system.

13. **Quality and delivery tooling**
   The repo is heavily test-driven for a template project:
   - `tests/*` mirrors the domain structure
   - there are QA readiness tests tied to the Supabase setup
   - Biome and Husky are used for formatting/checking and pre-commit enforcement
   This indicates the architecture is validated at both module and repository level, especially around schemas, access rules, and seed data.

14. **Documentation and product planning**
   The `docs/` tree includes database design, readiness checklists, and roadmap/spec documents. That suggests the repository is being used as both:
   - a runnable admin UI template
   - a working product platform with planned extensions around career-data visualization and production readiness
   In a diagram, docs should be treated as supporting architecture artifacts, not runtime components.

Main entry points: [`src/app/(main)/dashboard/layout.tsx`](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/layout.tsx) (Dashboard shell), [`src/lib/supabase`](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/lib/supabase) (Supabase), [`src/app/(main)/dashboard/employees`](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/employees) (Employees), [`src/server/server-actions.ts`](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/server/server-actions.ts) (Server actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_root_layout["Root layout<br/>next layout<br/>[layout.tsx]"]
  node_external_home["Public home<br/>route page<br/>[page.tsx]"]
  node_main_dashboard["Dashboard shell<br/>route layout<br/>[layout.tsx]"]
  node_auth_area["Auth screens<br/>route group"]
  node_employee_routes["Employees<br/>route surface"]
  node_admin_routes["Admin governance<br/>route surface"]
  node_talent_routes["Talent views<br/>route surface"]
  node_collab_routes["Collaboration tools<br/>route surface"]
  node_action_queue_route["Action queue<br/>route page<br/>[page.tsx]"]
  node_unauthorized_page["Unauthorized<br/>route page<br/>[page.tsx]"]
end

subgraph group_features["Feature Core"]
  node_employees_feature["Employee domain<br/>feature module"]
  node_career_plans_feature["Career plans<br/>feature module"]
  node_admin_feature["Admin domain<br/>feature module"]
  node_talent_feature["Talent analytics<br/>feature module"]
  node_reports_imports["Reports & imports<br/>feature module"]
  node_career_framework["Career framework<br/>domain model"]
end

subgraph group_platform["Platform"]
  node_sidebar_shell["Sidebar shell<br/>nav layout<br/>[app-sidebar.tsx]"]
  node_authz_lib["Access control<br/>auth lib"]
  node_prefs_store["Preferences<br/>state store"]
  node_ui_library["UI library<br/>component kit"]
  node_supabase_layer[("Supabase<br/>backend boundary")]
  node_server_actions["Server actions<br/>mutation layer<br/>[server-actions.ts]"]
  node_sidebar_config["Nav config<br/>navigation config<br/>[sidebar-items.ts]"]
end

subgraph group_ops["Ops & Quality"]
  node_db_migrations[("DB migrations<br/>schema set")]
  node_qa_checks["QA checks<br/>sql checks"]
  node_docs["Docs"]
end

node_root_layout -->|"wraps"| node_main_dashboard
node_root_layout -->|"serves"| node_external_home
node_main_dashboard -->|"uses"| node_sidebar_shell
node_sidebar_shell -->|"driven by"| node_sidebar_config
node_auth_area -->|"checks"| node_authz_lib
node_authz_lib -->|"denies to"| node_unauthorized_page
node_main_dashboard -->|"contains"| node_employee_routes
node_main_dashboard -->|"contains"| node_admin_routes
node_main_dashboard -->|"contains"| node_talent_routes
node_main_dashboard -->|"contains"| node_collab_routes
node_main_dashboard -->|"contains"| node_action_queue_route
node_employee_routes -->|"assembles"| node_employees_feature
node_employee_routes -->|"assembles"| node_career_plans_feature
node_admin_routes -->|"assembles"| node_admin_feature
node_talent_routes -->|"assembles"| node_talent_feature
node_action_queue_route -->|"mutates via"| node_server_actions
node_admin_routes -->|"mutates via"| node_server_actions
node_employee_routes -->|"mutates via"| node_server_actions
node_reports_imports -->|"mutates via"| node_server_actions
node_career_framework -->|"feeds"| node_admin_feature
node_career_framework -->|"feeds"| node_talent_feature
node_supabase_layer -->|"backs"| node_db_migrations
node_supabase_layer -->|"validated by"| node_qa_checks
node_admin_feature -->|"reads/writes"| node_supabase_layer
node_employees_feature -->|"reads/writes"| node_supabase_layer
node_talent_feature -->|"reads/writes"| node_supabase_layer
node_reports_imports -->|"reads/writes"| node_supabase_layer
node_prefs_store -->|"configures"| node_sidebar_shell
node_prefs_store -->|"supports"| node_ui_library
node_docs -->|"documents"| node_db_migrations
node_docs -->|"documents"| node_qa_checks
node_ui_library -->|"renders"| node_main_dashboard
node_ui_library -->|"renders"| node_employee_routes

click node_root_layout "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/layout.tsx"
click node_external_home "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(external)/page.tsx"
click node_main_dashboard "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/layout.tsx"
click node_auth_area "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/auth"
click node_employee_routes "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/employees"
click node_admin_routes "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/admin"
click node_talent_routes "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/talent"
click node_collab_routes "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard"
click node_action_queue_route "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/action-queue/page.tsx"
click node_unauthorized_page "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/unauthorized/page.tsx"
click node_sidebar_shell "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/_components/sidebar/app-sidebar.tsx"
click node_authz_lib "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/lib/auth"
click node_prefs_store "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/stores/preferences"
click node_ui_library "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/components/ui"
click node_supabase_layer "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/lib/supabase"
click node_server_actions "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/server/server-actions.ts"
click node_employees_feature "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/employees"
click node_career_plans_feature "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/career-plans"
click node_admin_feature "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/admin"
click node_talent_feature "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/talent"
click node_reports_imports "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/reports"
click node_career_framework "https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/career-framework"
click node_sidebar_config "https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/navigation/sidebar/sidebar-items.ts"
click node_db_migrations "https://github.com/thek1d21/gago-smartech-carrers/tree/main/supabase/migrations"
click node_qa_checks "https://github.com/thek1d21/gago-smartech-carrers/tree/main/supabase/qa"
click node_docs "https://github.com/thek1d21/gago-smartech-carrers/tree/main/docs"

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_layout,node_external_home,node_main_dashboard,node_auth_area,node_employee_routes,node_admin_routes,node_talent_routes,node_collab_routes,node_action_queue_route,node_unauthorized_page toneBlue
class node_employees_feature,node_career_plans_feature,node_admin_feature,node_talent_feature,node_reports_imports,node_career_framework toneAmber
class node_sidebar_shell,node_authz_lib,node_prefs_store,node_ui_library,node_supabase_layer,node_server_actions,node_sidebar_config toneMint
class node_db_migrations,node_qa_checks,node_docs toneRose
```

## Components

### App Router

Next.js route groups, layouts, and page surfaces.

- [Root layout](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/layout.tsx): next layout · Global app shell and styles. · `src/app/layout.tsx`
- [Public home](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(external)/page.tsx): route page · Public-facing entry point. · `src/app/(external)/page.tsx`
- [Dashboard shell](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/layout.tsx): route layout · Authenticated admin frame for most product areas. · `src/app/(main)/dashboard/layout.tsx`
- [Auth screens](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/auth): route group · Login and register flows with variant layouts. · `src/app/(main)/auth`
- [Employees](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/employees): route surface · Employee directory, profiles, assignments, and career plans. · `src/app/(main)/dashboard/employees`
- [Admin governance](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/admin): route surface · Skills, certifications, frameworks, review cycles, settings, templates, and audit. · `src/app/(main)/dashboard/admin`
- [Talent views](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard/talent): route surface · Skill matrix, talent map, pipeline, and certifications. · `src/app/(main)/dashboard/talent`
- [Collaboration tools](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/app/(main)/dashboard): route surface · Chat, mail, kanban, CRM, invoice, logistics, finance, productivity, analytics. · `src/app/(main)/dashboard`
- [Action queue](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/action-queue/page.tsx): route page · Operational work queue with status mutations. · `src/app/(main)/dashboard/action-queue/page.tsx`
- [Unauthorized](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/unauthorized/page.tsx): route page · Denied-access landing page. · `src/app/(main)/unauthorized/page.tsx`

### Feature Core

Domain logic and server-side workflows.

- [Employee domain](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/employees): feature module · Profiles, assignments, dossiers, queries, and career-plan workflows. · `src/features/employees`
- [Career plans](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/career-plans): feature module · Plan lists, selectors, progress tracking, and templates. · `src/features/career-plans`
- [Admin domain](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/admin): feature module · Users, skills, certifications, frameworks, settings, review cycles, governance. · `src/features/admin`
- [Talent analytics](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/talent): feature module · Skill matrix, talent map, promotion pipeline, and certification coverage. · `src/features/talent`
- [Reports & imports](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/reports): feature module · Reporting and employee import jobs. · `src/features/reports`
- [Career framework](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/features/career-framework): domain model · Skills, certifications, disciplines, levels, and scoring options. · `src/features/career-framework`

### Platform

Shared UI, auth, state, and persistence boundaries.

- [Sidebar shell](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/app/(main)/dashboard/_components/sidebar/app-sidebar.tsx): nav layout · Admin navigation, user menu, theme, and layout controls. · `src/app/(main)/dashboard/_components/sidebar/app-sidebar.tsx`
- [Access control](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/lib/auth): auth lib · Roles, route policy, and access checks. · `src/lib/auth`
- [Preferences](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/stores/preferences): state store · Layout and theme persistence across sessions. · `src/stores/preferences`
- [UI library](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/components/ui): component kit · Shared shadcn-style primitives and dashboard widgets. · `src/components/ui`
- [Supabase](https://github.com/thek1d21/gago-smartech-carrers/tree/main/src/lib/supabase): backend boundary · Client/server connectors and database-backed persistence. · `src/lib/supabase`
- [Server actions](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/server/server-actions.ts): mutation layer · Shared server mutation helpers and route-local actions. · `src/server/server-actions.ts`
- [Nav config](https://github.com/thek1d21/gago-smartech-carrers/blob/main/src/navigation/sidebar/sidebar-items.ts): navigation config · Sidebar items and user navigation definitions. · `src/navigation/sidebar/sidebar-items.ts`

### Ops & Quality

Database setup, QA, and supporting documentation.

- [DB migrations](https://github.com/thek1d21/gago-smartech-carrers/tree/main/supabase/migrations): schema set · Core schema, governance, review cycle, import/export, and seed migrations. · `supabase/migrations`
- [QA checks](https://github.com/thek1d21/gago-smartech-carrers/tree/main/supabase/qa): sql checks · Readiness scripts for demo, pilot, and scoped access. · `supabase/qa`
- [Docs](https://github.com/thek1d21/gago-smartech-carrers/tree/main/docs): docs · Database design, readiness, and roadmap/spec artifacts. · `docs`

## Connections

- Root layout → Dashboard shell: wraps · Global shell feeds the authenticated app frame.
- Root layout → Public home: serves · Public route is mounted under the root layout.
- Dashboard shell → Sidebar shell: uses · Dashboard frame is paired with the sidebar/navigation shell.
- Sidebar shell → Nav config: driven by · Sidebar content comes from navigation config.
- Auth screens → Access control: checks · Login/register flows sit beside access and route policy logic.
- Access control → Unauthorized: denies to · Failed access routes to the unauthorized screen.
- Dashboard shell → Employees: contains · Employee management lives inside the dashboard shell.
- Dashboard shell → Admin governance: contains · Admin governance routes are nested in the shell.
- Dashboard shell → Talent views: contains · Talent surfaces are part of the dashboard area.
- Dashboard shell → Collaboration tools: contains · Productivity and collaboration surfaces share the same frame.
- Dashboard shell → Action queue: contains · Operational queue is exposed as a dashboard page.
- Employees → Employee domain: assembles · Route components call into employee domain logic.
- Employees → Career plans: assembles · Employee career-plan flows depend on career-plan helpers.
- Admin governance → Admin domain: assembles · Admin pages are thin shells over admin feature modules.
- Talent views → Talent analytics: assembles · Talent pages render analytics from talent modules.
- Action queue → Server actions: mutates via · Queue status changes are concentrated in server actions.
- Admin governance → Server actions: mutates via · Admin CRUD screens use route-local actions.
- Employees → Server actions: mutates via · Employee/profile/career-plan updates go through actions.
- Reports & imports → Server actions: mutates via · Reporting and import workflows use shared action helpers.
- Career framework → Admin domain: feeds · Framework definitions underpin skills and certifications admin flows.
- Career framework → Talent analytics: feeds · Talent analytics consume framework levels, skills, and certifications.
- Supabase → DB migrations: backs · Database schema is defined and evolved in migrations.
- Supabase → QA checks: validated by · Readiness checks verify database and access behavior.
- Admin domain → Supabase: reads/writes · Governance data is persisted through Supabase.
- Employee domain → Supabase: reads/writes · Employee records and plans are database-backed.
- Talent analytics → Supabase: reads/writes · Talent views depend on persisted platform data.
- Reports & imports → Supabase: reads/writes · Import jobs and reporting persist through the backend boundary.
- Preferences → Sidebar shell: configures · Layout controls and theme state affect the app shell.
- Preferences → UI library: supports · UI primitives render preference-aware controls.
- Docs → DB migrations: documents · Docs capture database design and rollout guidance.
- Docs → QA checks: documents · Docs capture readiness and validation procedures.
- UI library → Dashboard shell: renders · Dashboard pages are built from shared UI primitives.
- UI library → Employees: renders · Employee screens compose shared cards, tables, and forms.