Skip to content

README.md

Latest commit

 

History

History
299 lines (236 loc) · 13.1 KB

README.md

File metadata and controls

299 lines (236 loc) · 13.1 KB
Raw

NexSAMS — Next-Gen Organization Management Platform

Structure your world. Empower your organization.

Next.js TypeScript Tailwind CSS Prisma License

Overview

NexSAMS is a production-grade, full-featured organization management platform built with a modern, opinionated tech stack. It provides comprehensive tools for managing organizational structure, tracking member performance, analyzing department health, generating intelligent insights, and exporting reports — all within a beautiful, responsive, dark-mode-ready interface.

Key Features

  • Dashboard — Real-time overview with animated metric cards, performance distribution charts, category score breakdowns, department overview, activity timeline, and smart AI-powered insights
  • Member Manager — Full CRUD with debounced search, multi-filter system (department, status), sortable columns with visibility toggle, bulk selection/actions, expandable row details, and a multi-step add/edit wizard with live Performance Index preview
  • Department Manager — Card and tree views, parent/child hierarchy, health score rings (SVG donuts), member avatar stacks, department detail drawer with score breakdowns, and member transfer workflows
  • Intelligence Panel — 6-dimension organization health gauge, LOWESS-style performance trend detection with anomaly markers and predicted next-quarter values, top performer leaderboard with medal animations, sortable performance matrix with color-scale cells, and dismissible smart insight cards
  • Reports Hub — Export members, departments, scores, and full org snapshots in CSV/JSON, with a report builder featuring column selection, format choice, date range filtering, and live preview
  • Command Palette — Global search and navigation (Cmd+K / Ctrl+K) with keyboard navigation, recent items, quick actions, and a blurred backdrop overlay
  • Notification Center — In-app notifications with type-based icons/coloring, read/unread filtering, and mark-all-read functionality
  • Settings — Organization profile editing, theme selection, and database management
  • Dark Mode — Premium, visually distinct dark theme with deep slate backgrounds, warm whites, and smooth 200ms cross-fade transitions
  • Accessibility — Semantic HTML, ARIA attributes, keyboard navigation, focus management, and 4.5:1+ color contrast ratios

Tech Stack

Layer Technology
Framework Next.js 16 (App Router)
Language TypeScript 5 (strict mode)
Styling Tailwind CSS 4 + shadcn/ui
Database Prisma ORM + SQLite
State Management Zustand (client state)
Charts Recharts
Icons Lucide React
Theming next-themes
Notifications Sonner
Command Palette cmdk
Forms React Hook Form + Zod validation
Animations Framer Motion + CSS keyframes

Project Structure

src/
├── app/
│   ├── globals.css              # Full design system: tokens, surfaces, glassmorphism, animations
│   ├── layout.tsx               # Root layout with fonts, ThemeProvider, Toaster
│   ├── page.tsx                 # Entry point → AppShell
│   └── api/
│       ├── organizations/route.ts  # Org CRUD
│       ├── members/route.ts       # Member CRUD with Zod validation
│       ├── departments/route.ts   # Department CRUD with hierarchy
│       ├── scores/route.ts        # Score CRUD
│       ├── analytics/route.ts     # 5 advanced algorithms (EMA, LOWESS, etc.)
│       ├── export/route.ts       # CSV/JSON export + full org snapshot
│       ├── ai-insights/route.ts  # Algorithmic AI-powered insights
│       ├── notifications/route.ts # Notification CRUD + mark-read
│       └── seed/route.ts          # Demo data: 48 members, 8 departments, 300+ scores
├── components/
│   ├── nexsams/
│   │   ├── app-shell.tsx          # Main layout: sidebar + topbar + content area
│   │   ├── top-bar.tsx            # Breadcrumbs, search trigger, notification bell, theme toggle
│   │   ├── command-palette.tsx    # Global Cmd+K command palette
│   │   ├── dashboard.tsx          # Metric cards, charts, insights, activity feed
│   │   ├── member-manager.tsx     # Full member table with all features
│   │   ├── department-manager.tsx # Card/tree views, health rings, detail drawer
│   │   ├── analytics-panel.tsx    # Health gauge, trend chart, leaderboard, matrix
│   │   ├── reports-hub.tsx        # Export cards, report builder, org summary
│   │   ├── settings-panel.tsx     # Org settings, theme selection, danger zone
│   │   ├── notification-center.tsx # Notification list with filtering
│   │   ├── org-summary.tsx        # Organization summary report component
│   │   └── shared.tsx             # AnimatedNumber, Sparkline, timeAgo, utils
│   └── ui/                       # 40+ shadcn/ui components
├── hooks/
│   ├── use-analytics.ts          # Analytics data fetching with SWR pattern
│   ├── use-members.ts            # Member + department data fetching
│   ├── use-departments.ts       # Department data fetching
│   ├── use-local-storage.ts      # Type-safe localStorage with SSR guard
│   ├── use-mobile.ts             # Mobile viewport detection
│   └── use-toast.ts              # Toast notification wrapper
├── lib/
│   ├── db.ts                    # Prisma client singleton
│   ├── utils.ts                  # cn(), nameToColor(), getInitials(), performance helpers
│   ├── api-response.ts           # Unified API response: apiSuccess, apiError, withErrorHandler, validateBody
│   └── validations.ts            # Zod schemas for all entities
├── store/
│   └── app-store.ts             # Zustand store: section, sidebar, refresh state
├── types/
│   └── index.ts                 # Full TypeScript types for all entities and analytics
└── prisma/
    └── schema.prisma             # 6 models: Organization, Department, Member, Score, Activity, Notification

Intelligence Algorithms

The analytics engine includes 5 production-grade algorithms:

1. Performance Index (EMA-Based)

Calculates weighted performance using Exponential Moving Average (alpha=0.3) that weights recent scores more heavily. Returns confidence score based on category coverage and flags outlier scores beyond 2 standard deviations.

Time Complexity: O(n)

2. Organization Health Score (6 Dimensions)

Composite health score from 6 sub-dimensions, each scored 0-100:

  • Engagement Rate — Active member percentage
  • Performance Consistency — Inverse of coefficient of variation
  • Structural Balance — Department balance index
  • Growth Velocity — Normalized quarterly trend slope
  • Retention Rate — Active + on-leave vs total ratio
  • Coverage Rate — % members with scores in all 4 categories

3. Performance Trend Detection (LOWESS-style)

Linear regression with R-squared confidence, anomaly detection (1.5x average deviation threshold), next-quarter prediction, and trend direction classification (up/down/stable with 2% threshold).

4. Department Balance Index (Extended)

Weighted balance incorporating member count, average performance, score coverage, and active rate per department. Returns overall balance and per-department rankings with imbalance driver identification.

5. Smart Insight Engine

Generates actionable insights across 11 categories including health checks, trend detection, inactivity alerts, score coverage gaps, star performer retention risk, stagnation detection, department momentum, structural depth alerts, understaffing, and low performance warnings. Each insight includes priority scoring (0-10) and recommended actions.

Design System

Color Architecture

  • Primary: Emerald (oklch-based, vibrant in both themes)
  • Light Mode: Warm off-white backgrounds, deep charcoal text
  • Dark Mode: Deep slate backgrounds, warm white text, glassmorphism with SVG noise grain overlay
  • 12-shade color ramps for primary, secondary, accent, neutral, success, warning, danger, info

Surface Hierarchy

  • surface-0: Base page background
  • surface-1: Cards and content containers
  • surface-2: Elevated/modals
  • surface-3: Floating elements (tooltips, popovers)

Utility Classes

  • .glass — Frosted glassmorphism surface with backdrop-filter blur
  • .glass-card — Elevated glass card with rounded corners
  • .hover-glow — Hover shadow elevation effect
  • .animate-shimmer — Skeleton loading placeholder
  • .animate-fade-in-up — Entrance animation
  • .animate-scale-in — Modal entrance animation
  • .custom-scrollbar — Custom styled scrollbar

Typography

  • Headings: Plus Jakarta Sans (geometric sans-serif)
  • Data/Mono: JetBrains Mono (high-legibility monospace)
  • Scale: --text-xs through --text-4xl with leading/tracking companions

Getting Started

Prerequisites

  • Node.js 18+
  • npm, yarn, or bun

Installation

# Clone the repository
git clone <repository-url>
cd nexsams

# Install dependencies
bun install

# Set up database
cp .env.example .env
bun run db:push
bun run db:generate

# Start development server
bun run dev

The application auto-seeds with demo data on first load (48 members, 8 departments, 300+ score entries, 30 activity logs, 10 notifications).

Environment Variables

DATABASE_URL="file:./db/custom.db"

API Endpoints

Organizations

Method Endpoint Description
GET /api/organizations List organizations
POST /api/organizations Create organization
PUT /api/organizations Update organization

Members

Method Endpoint Description
GET /api/members?orgId=...&search=...&departmentId=...&status=... List members (with filters)
POST /api/members Create member (Zod validated)
PUT /api/members Update member (Zod validated)
DELETE /api/members?id=... Delete member

Departments

Method Endpoint Description
GET /api/departments?orgId=... List departments with hierarchy
POST /api/departments Create department
PUT /api/departments Update department
DELETE /api/departments?id=... Delete department

Analytics

Method Endpoint Description
GET /api/analytics?orgId=... Full analytics payload (all 5 algorithms)

AI Insights

Method Endpoint Description
POST /api/ai-insights Generate AI-powered organizational insights

Export

Method Endpoint Description
GET /api/export?orgId=...&type=members&format=csv Export members
GET /api/export?orgId=...&type=departments&format=json Export departments
GET /api/export?orgId=...&type=scores&format=csv Export scores
GET /api/export?orgId=...&type=snapshot&format=json Full org snapshot

Notifications

Method Endpoint Description
GET /api/notifications?orgId=... List notifications with unread count
PUT /api/notifications Mark notification(s) as read

Seed

Method Endpoint Description
POST /api/seed Seed database with demo data

Keyboard Shortcuts

Shortcut Action
Cmd+K / Ctrl+K Open command palette
Cmd+1 Navigate to Dashboard
Cmd+2 Navigate to Members
Cmd+3 Navigate to Departments
Cmd+4 Navigate to Intelligence
Cmd+5 Navigate to Reports
Escape Close modals/command palette

Performance Optimizations

  • Dynamic imports for heavy components (Analytics charts, Command palette)
  • React.memo and useMemo for expensive computations
  • Debounced search (300ms) to reduce API calls
  • Skeleton loading for all data-fetching components
  • Sticky headers in tables for large datasets
  • Custom scrollbar styling for consistent UX

Accessibility

  • Semantic HTML elements throughout
  • ARIA labels, roles, and descriptions on all interactive elements
  • Keyboard navigation support for all modals and drawers
  • Focus trap management in dialogs
  • Screen reader announcements via aria-live regions
  • Color contrast ratio 4.5:1+ for all text/surface combinations
  • Reduced motion support via prefers-reduced-motion media query

License

MIT License. Built with Next.js, TypeScript, Tailwind CSS, Prisma, and the shadcn/ui component library.