How thek1d21/gago-smartech-carrers works
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: layout.tsx Dashboard shell · supabase Supabase · employees Employees · server-actions.ts Server actions
Components 26
App Router
Next.js route groups, layouts, and page surfaces.
- Root layout · Global app shell and styles.
src/app/layout.tsx - Public home · Public-facing entry point.
src/app/(external)/page.tsx - Dashboard shell · Authenticated admin frame for most product areas.
src/app/(main)/dashboard/layout.tsx - Auth screens · Login and register flows with variant layouts.
src/app/(main)/auth - Employees · Employee directory, profiles, assignments, and career plans.
src/app/(main)/dashboard/employees - Admin governance · Skills, certifications, frameworks, review cycles, settings, templates, and audit.
src/app/(main)/dashboard/admin - Talent views · Skill matrix, talent map, pipeline, and certifications.
src/app/(main)/dashboard/talent - Collaboration tools · Chat, mail, kanban, CRM, invoice, logistics, finance, productivity, analytics.
src/app/(main)/dashboard - Action queue · Operational work queue with status mutations.
src/app/(main)/dashboard/action-queue/page.tsx - Unauthorized · Denied-access landing page.
src/app/(main)/unauthorized/page.tsx
Feature Core
Domain logic and server-side workflows.
- Employee domain · Profiles, assignments, dossiers, queries, and career-plan workflows.
src/features/employees - Career plans · Plan lists, selectors, progress tracking, and templates.
src/features/career-plans - Admin domain · Users, skills, certifications, frameworks, settings, review cycles, governance.
src/features/admin - Talent analytics · Skill matrix, talent map, promotion pipeline, and certification coverage.
src/features/talent - Reports & imports · Reporting and employee import jobs.
src/features/reports - Career framework · Skills, certifications, disciplines, levels, and scoring options.
src/features/career-framework
Platform
Shared UI, auth, state, and persistence boundaries.
- Sidebar shell · Admin navigation, user menu, theme, and layout controls.
src/app/(main)/dashboard/_components/sidebar/app-sidebar.tsx - Access control · Roles, route policy, and access checks.
src/lib/auth - Preferences · Layout and theme persistence across sessions.
src/stores/preferences - UI library · Shared shadcn-style primitives and dashboard widgets.
src/components/ui - Supabase · Client/server connectors and database-backed persistence.
src/lib/supabase - Server actions · Shared server mutation helpers and route-local actions.
src/server/server-actions.ts - Nav config · Sidebar items and user navigation definitions.
src/navigation/sidebar/sidebar-items.ts
Ops & Quality
Database setup, QA, and supporting documentation.
- DB migrations · Core schema, governance, review cycle, import/export, and seed migrations.
supabase/migrations - QA checks · Readiness scripts for demo, pilot, and scoped access.
supabase/qa - Docs · Database design, readiness, and roadmap/spec artifacts.
docs
Connections 33
- 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.