Productivity Tracker Frontend

A modern, full-featured productivity tracking application built with React, TanStack Router, and TanStack Query.

Quick Start

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Open http://localhost:5173

That's it! The app will connect to your backend at http://localhost:8000 by default.

First Time Using This?

1. Register an account at /auth/register
2. Login at /auth/login
3. Explore - The home page shows everything you can do

What Can This App Do?

For Everyone

• Track Tasks - Personal to-do lists and task management
• Manage Projects - View projects, track progress, see team assignments
• Collaborate - Teams, departments, and shared workspaces
• Stay Informed - Notifications and activity feeds
• Customize - Choose your theme (Light/Dark/Nature)

For Administrators (Superusers)

• Manage Users - Add, edit, activate/deactivate users
• Control Access - Create roles, assign permissions
• Invite Users - Send email invitations with domain whitelisting
• System Config - Manage system-wide settings

How Navigation Works

This app has two sidebars to keep things organized:

Main Sidebar (Right Side)

Your main navigation - always visible on desktop:

• Dashboard, Tasks, Projects
• Teams, Departments, Workspaces
• Admin (if you're a superuser)
• Profile, Settings, Notifications

Feature Sidebar (Left Side)

Appears when you're in a feature with multiple pages:

• Admin section: Jump between Users → Roles → Permissions → Invites → Domains
• Projects: Switch between All → Active → Archived
• Tasks: View All → My Tasks → Upcoming → Completed
• Dashboard: Overview → Analytics → Activity → Reports

On mobile? Use the hamburger menu (☰) in the top-left corner.

Understanding the Code Structure

src/
├── routes/                    # All your pages
│   ├── _authenticated/        # Pages that require login
│   │   └── _layout/           # Main app pages
│   │       ├── admin/         # Admin pages (superuser only)
│   │       ├── dashboard/     # Dashboard pages
│   │       ├── tasks/         # Task pages
│   │       └── ...
│   └── auth/                  # Login/register pages
│
├── components/                # Reusable UI pieces
│   ├── ui/                    # Basic components (buttons, cards, etc.)
│   ├── DataTable.tsx          # Sortable, searchable tables
│   ├── MainSidebar.tsx        # Right sidebar
│   ├── FeatureSidebar.tsx     # Left sidebar
│   └── ...
│
├── hooks/                     # React hooks
│   ├── use-auth.ts            # Authentication & user info
│   ├── use-api.ts             # API calls (auto-generated)
│   └── use-theme.ts           # Theme switching
│
└── lib/                       # Utilities
    ├── api-client.ts          # API configuration
    └── openapi/               # Auto-generated from backend

How Authentication Works

1. You login with username/password
2. Backend sets a secure cookie (you can't see it in JavaScript - that's good!)
3. Your user info is stored locally so it persists when you refresh
4. All API calls automatically include your cookie
5. If you're not logged in, you get redirected to /auth/login

Role-Based Access: Some pages check if you have the right permissions:

• Admin pages need superuser or admin role
• You can check permissions with hasPermission('tasks', 'create')
• You can check roles with hasRole('admin')

Working With the API

All API calls are auto-generated from your backend's OpenAPI spec. You get:

• Type-safe functions
• React Query hooks
• Automatic error handling

Example:

import { useUsers } from '@/hooks'

function UsersList() {
  const { data: users, isLoading } = useUsers()
  
  if (isLoading) return <div>Loading...</div>
  
  return (
    <ul>
      {users?.map(user => <li key={user.id}>{user.username}</li>)}
    </ul>
  )
}

All mutations (create/update/delete) show toast notifications automatically!

Common Tasks

Add a New Page

1. Create a file in src/routes/, e.g., src/routes/_authenticated/_layout/my-page.tsx
2. Add the route code:

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_authenticated/_layout/my-page')({
  component: MyPageComponent,
})

function MyPageComponent() {
  return <div>My New Page</div>
}

3. Run pnpm run build:routes to regenerate routes
4. Navigate to /my-page

Add a Feature Sidebar

If your feature has multiple sub-pages, use a FeatureSidebar:

1. Create a layout file: src/routes/_authenticated/_layout/my-feature.tsx
2. Add navigation items and use <Outlet /> for child routes
3. Create child pages in a folder: src/routes/_authenticated/_layout/my-feature/

See dashboard.tsx or projects.tsx for examples.

Protect a Page

Add a permission check:

export const Route = createFileRoute('/admin/users')({
  beforeLoad: () => {
    const { isSuperuser, hasRole } = useAuth.getState()
    if (!isSuperuser() && !hasRole('admin')) {
      throw redirect({ to: '/' })
    }
  },
  component: UsersComponent,
})

Change the Theme Colors

Edit src/index.css - all colors use CSS variables:

:root {
  --primary: 222.2 47.4% 11.2%;  /* Your brand color */
  --background: 0 0% 100%;        /* Page background */
  /* ... etc */
}

Available Scripts

pnpm dev              # Start dev server
pnpm build            # Build for production
pnpm preview          # Preview production build
pnpm lint             # Check code quality
pnpm typecheck        # Check TypeScript types
pnpm test             # Run tests
pnpm test:watch       # Run tests in watch mode

Environment Variables

Create a .env.local file if your backend is not at http://localhost:8000:

VITE_API_BASE_URL=http://your-backend-url/api/v1.0

Tech Stack

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool (super fast!)
• TanStack Router - File-based routing with type safety
• TanStack Query - Server state management
• Tailwind CSS - Styling
• Radix UI - Accessible component primitives
• Zustand - Client state (authentication)
• Vitest - Testing

Need More Details?

• Architecture deep-dive: See docs/ADVANCED_SETUP.md
• Router guide: See docs/ROUTER_GUIDE.md
• Auth flow explained: See docs/AUTH_SETUP.md
• Admin section structure: See docs/ADMIN_ROUTES_FIXED.md

Troubleshooting

"Can't login"

• Check backend is running at http://localhost:8000
• Check backend CORS allows credentials
• Check Network tab for cookie being set

"Routes not working"

• Run pnpm run build:routes after adding new route files
• Check file naming follows TanStack Router conventions

"Types are wrong"

• Backend API changed? Regenerate with pnpm openapi-ts
• Clear .tanstack folder and restart dev server

---

Questions? Check the docs folder or dive into the code - it's well-structured and commented!