Nexus Learning OS

A next-generation student learning dashboard built with Next.js 15, Supabase, Tailwind CSS, and Framer Motion.

---

Overview

Nexus Learning OS is a dark-mode learning dashboard that surfaces real course data from a Supabase database alongside activity tracking, goal management, achievement badges, and AI-powered study suggestions. The focus is clean architecture, readable code, and a polished but professional UI — not visual spectacle.

---

Features

• Real Supabase integration — Course cards are fetched server-side and rendered dynamically
• Bento grid layout — Responsive 4-column desktop, 2-column tablet, single-column mobile
• Framer Motion animations — Staggered card entrances, progress bar fills, animated charts
• Activity heatmap — GitHub-style contribution grid with hover tooltips
• AI study suggestions — Personalized recommendations panel
• Goal tracker — Daily and weekly progress bars with animated progress ring
• Achievement badges — Unlock-style badge grid
• Accessibility — ARIA labels, keyboard navigation, visible focus states, semantic HTML
• Loading skeletons — Shimmer placeholders match the live layout
• Error boundary — Graceful fallback with retry button

---

Tech Stack

Layer	Technology
Framework	Next.js 15 App Router
Language	TypeScript (strict)
Styling	Tailwind CSS
Animation	Framer Motion
Database	Supabase
Icons	Lucide React
Fonts	Geist (Next.js font)
Deployment	Vercel

---

Project Structure

nexus-learning-os/
├── app/
│   ├── layout.tsx          # Root layout, fonts, metadata
│   ├── page.tsx            # Dashboard page (Server Component)
│   ├── loading.tsx         # Full-page skeleton
│   └── error.tsx           # Error boundary
├── components/
│   ├── sidebar/
│   │   └── Sidebar.tsx     # Desktop nav (Client)
│   ├── dashboard/
│   │   ├── HeroCard.tsx        # Welcome tile with stats
│   │   ├── CourseGrid.tsx      # Server Component — Supabase fetch
│   │   ├── CourseCard.tsx      # Individual course tile (Client)
│   │   ├── ActivityCard.tsx    # Heatmap (Client)
│   │   ├── AIAssistantCard.tsx # Study suggestions (Client)
│   │   ├── AnalyticsCard.tsx   # SVG line chart (Client)
│   │   ├── GoalCard.tsx        # Goal tracker (Client)
│   │   ├── AchievementCard.tsx # Badge grid (Client)
│   │   └── DashboardHeader.tsx # Page header (Client)
│   └── ui/
│       ├── MobileNav.tsx       # Bottom nav bar
│       ├── ProgressRing.tsx    # SVG ring component
│       ├── SkeletonCard.tsx    # Shimmer placeholder
│       └── SectionLabel.tsx    # Section heading
├── lib/
│   └── supabase/
│       └── server.ts       # Supabase SSR client
├── hooks/                  # Reserved for custom hooks
├── types/
│   └── index.ts            # TypeScript interfaces
├── .env.example
└── README.md

---

Supabase Integration

Database schema expected

CREATE TABLE courses (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  progress INTEGER NOT NULL DEFAULT 0,
  icon_name TEXT NOT NULL DEFAULT 'BookOpen',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Supported icon_name values

BookOpen, Cpu, Brain, Cloud, Code, Database, Globe, Layers, Palette, Zap, BarChart, Lock

Server Component strategy

CourseGrid is a React Server Component. It calls createClient() from lib/supabase/server.ts, runs the query, and returns rendered CourseCard elements. A <Suspense> boundary in app/page.tsx shows skeleton cards while the fetch resolves.

---

Framer Motion Strategy

• Entrance animations — opacity: 0 → 1, y: 24 → 0, staggered via delay per card
• Spring config — type: "spring", stiffness: 300, damping: 24
• Progress bars — scaleX: 0 → progress% using transformOrigin: "left"
• Progress rings — strokeDashoffset animated from full to partial
• Heatmap cells — Scale + opacity entrance, staggered by index
• GPU safety — Only transform and opacity are animated; no layout properties

---

Accessibility Features

• Semantic HTML: <nav>, <main>, <header>, <section>, <article>, <ul>, <li>
• aria-label on all interactive and landmark elements
• aria-current="page" on active nav item
• role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax on progress bars
• role="alert" and aria-live="polite" on error and empty states
• Visible :focus-visible outline using outline: 2px solid #6366f1
• Keyboard navigable sidebar and mobile nav

---

Performance Notes

• Animations use transform and opacity only — no layout-triggering properties
• will-change: transform applied to hover targets
• Images avoided entirely — icon-based UI only
• Fonts loaded via next/font/google with display swap
• Course data fetched once server-side, no client waterfall

---

Local Setup

# 1. Clone and install
git clone <your-repo-url>
cd nexus-learning-os
npm install

# 2. Set environment variables
cp .env.example .env.local
# Fill in your Supabase URL and publishable key

# 3. Run dev server
npm run dev

Visit http://localhost:3000.

---

Vercel Deployment

1. Push the project to a GitHub repository.
2. Import the repository in Vercel.
3. Add environment variables in the Vercel project settings:
   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
4. Deploy. Vercel auto-detects Next.js; no extra config needed.