app

Imported from patilbhau1/ai-life-planner (app/AGENTS.md). Install upstream with npx skills add patilbhau1/ai-life-planner --skill app. Copyright stays with the author.

AI-Powered Life Planner - Agent Guide

This document provides essential information for AI coding agents working on this project.

Project Overview

The AI-Powered Life Planner is a full-stack web application for personal goal management and life vision planning. It helps users:

• Define life vision statements and long-term goals
• Create hierarchical goal structures (Life Vision → 10-Year Goals → 3-Year Goals → Tasks)
• Track progress with visual indicators and progress history
• Receive AI-generated insights and coaching
• Manage daily focus and checklists
• Visualize goals through timelines and mind maps

Demo Credentials:

• Email: demo@lifeplanner.app
• Password: (any password works for demo user)

Technology Stack

Frontend

• React 19.2.0 - UI library with StrictMode
• TypeScript 5.9.3 - Type safety
• Vite 7.2.4 - Build tool and dev server
• React Router DOM 7.13.1 - Client-side routing
• Tailwind CSS 3.4.19 - Utility-first styling
• shadcn/ui - 40+ accessible UI components (Radix UI based)
• Recharts 2.15.4 - Data visualization
• date-fns 4.1.0 - Date manipulation
• Zod 4.3.5 - Schema validation
• React Hook Form 7.70.0 - Form management

Backend

• Express.js 5.2.1 - Node.js web framework
• bcryptjs 3.0.3 - Password hashing
• jsonwebtoken 9.0.3 - JWT authentication
• cookie-parser 1.4.7 - Cookie parsing
• cors 2.8.6 - Cross-origin requests

Database

• Prisma ORM 7.5.0 - Database toolkit
• SQLite - Local development database (dev.db)
• @prisma/adapter-libsql - LibSQL/Turso compatibility
• Schema designed for easy migration to PostgreSQL/Supabase in production

Fonts

• Inter - Body text
• Sora - Headings

Project Structure

├── src/
│   ├── components/          # React components
│   │   ├── ui/              # 40+ shadcn/ui components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   └── ... (accordion, alert, dialog, form, etc.)
│   │   ├── AICompanion.tsx  # AI chat interface
│   │   ├── Layout.tsx       # App shell with sidebar
│   │   ├── LifeVisionFlow.tsx
│   │   ├── Timeline.tsx
│   │   ├── GoalColumns.tsx
│   │   ├── TodaysFocus.tsx
│   │   ├── AllTimeWidget.tsx
│   │   ├── LeftRail.tsx
│   │   └── TopBar.tsx
│   ├── pages/               # Route page components
│   │   ├── DashboardPage.tsx
│   │   ├── VisionPage.tsx
│   │   ├── PlansPage.tsx
│   │   ├── DailyFocusPage.tsx
│   │   ├── MindMapPage.tsx
│   │   ├── CalendarPage.tsx
│   │   ├── KnowledgePage.tsx
│   │   ├── ProgressPage.tsx
│   │   ├── AIMemoryPage.tsx
│   │   ├── SettingsPage.tsx
│   │   └── LoginPage.tsx
│   ├── hooks/               # Custom React hooks
│   │   ├── useAuth.tsx      # Authentication context & provider
│   │   ├── useAI.ts         # AI insights and chat
│   │   ├── useChecklists.ts # Checklist CRUD operations
│   │   └── usePlanNodes.ts  # Plan node management
│   ├── lib/                 # Utilities
│   │   ├── api.ts           # API client functions
│   │   ├── utils.ts         # cn() Tailwind utility
│   │   └── db/              # Database client (server-side only)
│   ├── types/               # TypeScript type definitions
│   │   └── index.ts
│   ├── App.tsx              # Root component with routes
│   ├── main.tsx             # App entry point
│   ├── index.css            # Global styles & Tailwind
│   └── App.css              # App-specific styles
├── prisma/
│   ├── schema.prisma        # Database schema
│   ├── seed.ts              # Demo data seeding script
│   └── migrations/          # Database migrations
├── server.cjs               # Express backend (CommonJS)
├── vite.config.ts           # Vite configuration
├── tailwind.config.js       # Tailwind CSS configuration
├── eslint.config.js         # ESLint configuration
├── tsconfig.json            # TypeScript base config
├── tsconfig.app.json        # App-specific TS config
├── components.json          # shadcn/ui configuration
└── .env                     # Environment variables

Development Setup

Prerequisites

• Node.js 20+
• npm or compatible package manager

Installation

npm install

Running the Application

Full Development (Recommended):

npm run dev:full

This runs both the backend server (port 3001) and frontend dev server (port 5173) concurrently.

Frontend Only:

npm run dev

Runs only the Vite dev server on port 5173.

Backend Only:

npm run server

Runs only the Express server on port 3001.

Seeding Demo Data

npx prisma db seed

This creates a demo user with sample goals, checklists, and AI insights.

Build Commands

Database

Schema Overview

Core Models:

• Profile - User accounts with auth credentials
• PlanNode - Hierarchical goals/tasks (self-referencing parent-child)
• Checklist - Task items under PlanNodes
• NodeConnection - Custom relationships between nodes
• AiInsight - AI-generated suggestions and motivation
• AiConversation - Chat history with AI companion
• ContentRecommendation - Curated learning resources
• ProgressHistory - Historical progress tracking

Key Enums:

• NodeType: VISION, GOAL, MILESTONE, TASK, HABIT, NOTE
• TimeHorizon: LIFE, TEN_YEARS, THREE_YEARS, ONE_YEAR, QUARTER, MONTH, WEEK, DAY
• Category: CAREER, HEALTH, RELATIONSHIPS, FINANCE, LEARNING, CREATIVE, SPIRITUAL, OTHER
• NodeStatus: ACTIVE, COMPLETED, ARCHIVED, DEFERRED

Prisma Commands

# Generate Prisma client after schema changes
npx prisma generate

# Run migrations
npx prisma migrate dev

# Reset database and run migrations
npx prisma migrate reset

# Seed database with demo data
npx prisma db seed

# Open Prisma Studio (GUI)
npx prisma studio

Database Configuration

Development uses SQLite via file:./dev.db. For production, modify prisma/schema.prisma:

datasource db {
  provider = "postgresql"  // or "mysql"
  url      = env("DATABASE_URL")
}

Authentication

JWT-Based Authentication

1. User logs in with email/password
2. Server validates credentials and returns JWT token + user data
3. Token is stored in localStorage
4. Subsequent API calls include token in Authorization: Bearer <token> header
5. Token expires after 7 days

Protected Routes

Frontend: Routes wrapped in <ProtectedRoute> component redirect to /login if not authenticated.

Backend: Routes use authenticateToken middleware:

const authenticateToken = (req, res, next) => {
  const token = req.headers['authorization']?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Access denied' });
  // Verify JWT...
};

Demo User

The demo user (demo@lifeplanner.app) accepts any password for easy testing.

API Structure

All API endpoints are prefixed with /api and defined in server.cjs:

Authentication

• POST /api/auth/register - Create new account
• POST /api/auth/login - Login
• GET /api/auth/me - Get current user (protected)
• POST /api/auth/check-email - Check if email exists

Profiles

• GET /api/profiles/:id - Get profile (protected)
• PATCH /api/profiles/:id - Update profile (protected)

Plan Nodes

• GET /api/nodes - Get all user nodes (protected)
• GET /api/nodes/tree - Get hierarchical tree (protected)
• GET /api/nodes/vision - Get vision nodes (protected)
• GET /api/nodes/:id - Get single node (protected)
• POST /api/nodes - Create node (protected)
• PATCH /api/nodes/:id - Update node (protected)
• PATCH /api/nodes/:id/progress - Update progress (protected)
• DELETE /api/nodes/:id - Delete node (protected)

Checklists

• GET /api/checklists?nodeId= - Get checklists for node (protected)
• POST /api/checklists - Create checklist (protected)
• PATCH /api/checklists/:id - Update checklist (protected)
• POST /api/checklists/:id/toggle - Toggle completion (protected)
• DELETE /api/checklists/:id - Delete checklist (protected)

AI Features

• GET /api/ai/insights - Get user insights (protected)
• GET /api/ai/insights/unread - Get unread insights (protected)
• POST /api/ai/insights - Create insight (protected)
• POST /api/ai/insights/:id/read - Mark as read (protected)
• GET /api/ai/chat - Get chat history (protected)
• POST /api/ai/chat - Send message (protected)
• DELETE /api/ai/chat - Clear history (protected)
• GET /api/ai/stats - Get AI stats (protected)

Code Style Guidelines

Naming Conventions

• Components: PascalCase (e.g., DashboardPage.tsx, Button.tsx)
• Hooks: camelCase with use prefix (e.g., useAuth.tsx, usePlanNodes.ts)
• Utilities: camelCase (e.g., api.ts, utils.ts)
• Types/Interfaces: PascalCase (e.g., PlanNode, User)
• Constants: UPPER_SNAKE_CASE for true constants

File Organization

• One main component per file
• Co-locate related components (e.g., Layout.tsx includes layout components)
• Export from index files for cleaner imports

Styling

• Use Tailwind CSS utility classes
• Custom colors defined in CSS variables (see src/index.css)
• Use cn() utility from src/lib/utils.ts for conditional classes
• Component-specific styles in App.css

Path Aliases

• @/ maps to src/ directory
• Used consistently across the codebase

Module Systems

• Client code: ES modules (import/export)
• Server code: CommonJS (require/module.exports) - server.cjs

Testing

Current State: No test suite is currently configured. To add testing:

# Recommended stack:
npm install -D vitest @testing-library/react @testing-library/jest-dom

Security Considerations

Current Implementation

• Passwords hashed with bcrypt (salt rounds: 10)
• JWT tokens with 7-day expiration
• CORS restricted to http://localhost:5173
• Protected routes verify token on both client and server

Production Recommendations

• Change JWT_SECRET in environment variables
• Use HTTPS in production
• Implement rate limiting on auth endpoints
• Add CSRF protection for cookie-based auth
• Store tokens in httpOnly cookies instead of localStorage
• Validate all user inputs with Zod schemas

Deployment Notes

Environment Variables

Required for production (.env):

DATABASE_URL="postgresql://..."  # or your production DB
JWT_SECRET="your-strong-secret-key"
PORT=3001

Build for Production

npm run build

Output goes to dist/ directory.

Production Server

npm start

Serves both API and static files from dist/.

Database Migration for Production

1. Update prisma/schema.prisma with production database provider
2. Run npx prisma migrate deploy in production
3. Run npx prisma db seed if seeding is needed

Common Tasks

Adding a New Page

1. Create component in src/pages/
2. Add route in src/App.tsx
3. Add navigation item in src/components/LeftRail.tsx

Adding a New API Endpoint

1. Add route handler in server.cjs
2. Use authenticateToken middleware for protected routes
3. Add corresponding function in src/lib/api.ts

Modifying Database Schema

1. Edit prisma/schema.prisma
2. Run npx prisma migrate dev --name <description>
3. Update prisma/seed.ts if needed
4. Regenerate Prisma client: npx prisma generate

Troubleshooting

Common Issues

"Cannot find module '@/...'"

• Ensure TypeScript path aliases are configured correctly
• Restart TypeScript language service

Database connection errors

• Check dev.db file exists
• Run npx prisma generate after schema changes

CORS errors

• Ensure both servers are running (ports 5173 and 3001)
• Check CORS origin in server.cjs matches frontend URL

Authentication issues

• Clear localStorage and re-login
• Check JWT_SECRET consistency

Resources

• shadcn/ui Documentation
• Prisma Documentation
• Tailwind CSS Documentation
• React Router Documentation