Add comprehensive documentation with JSDoc comments and contributing guidelines

README.md

@@ -99,8 +99,174 @@ Database version control and schema:
 
 ## Getting Started
 
-[Add setup instructions here]
+### Prerequisites
+
+Before setting up the project, ensure you have the following installed:
+
+- **Node.js** (v18 or higher) - [Download here](https://nodejs.org/)
+- **npm** (comes with Node.js) or **yarn**
+- **PostgreSQL** (v14 or higher) - [Download here](https://www.postgresql.org/download/)
+- **Git** - [Download here](https://git-scm.com/)
+
+### Installation & Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/ICPCPlatform/icpc-platform.git
+   cd icpc-platform
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Environment Configuration**
+
+   Create a `.env.local` file in the root directory:
+   ```bash
+   cp .env.example .env.local
+   ```
+
+   Configure the following environment variables:
+   ```env
+   # Database
+   DATABASE_URL="postgresql://username:password@localhost:5432/icpc_platform"
+
+   # Session Management
+   SESSION_SECRET="your-super-secret-session-key-here"
+
+   # Email Service (Resend)
+   RESEND_API_KEY="your-resend-api-key"
+
+   # Application URL
+   URL="localhost:3000"
+   NODE_ENV="development"
+   ```
+
+4. **Database Setup**
+
+   Create a PostgreSQL database:
+   ```sql
+   CREATE DATABASE icpc_platform;
+   ```
+
+   Run database migrations:
+   ```bash
+   npm run db:migrate
+   ```
+
+   (Optional) Seed with sample data:
+   ```bash
+   npm run db:seed
+   ```
+
+5. **Start Development Server**
+   ```bash
+   npm run dev
+   ```
+
+   The application will be available at [http://localhost:3000](http://localhost:3000)
+
+### Learning Resources
+
+#### For New Contributors
+- **Next.js Documentation**: [nextjs.org/docs](https://nextjs.org/docs) - Learn about App Router, API routes, and React Server Components
+- **TypeScript Handbook**: [typescriptlang.org/docs](https://www.typescriptlang.org/docs/) - Essential for type-safe development
+- **Drizzle ORM Guide**: [orm.drizzle.team](https://orm.drizzle.team/) - Database operations and schema management
+- **Tailwind CSS**: [tailwindcss.com/docs](https://tailwindcss.com/docs) - Utility-first CSS framework
+
+#### ICPC & Competitive Programming
+- **ICPC Official Site**: [icpc.global](https://icpc.global/) - Contest rules, problems, and resources
+- **Codeforces**: [codeforces.com](https://codeforces.com/) - Practice problems and contests
+- **CP-Algorithms**: [cp-algorithms.com](https://cp-algorithms.com/) - Algorithm implementations and explanations
+
+#### Key Project Documents
+- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
+- **[API Documentation](./src/app/api/README.md)** - REST API endpoints and usage
+- **[Database Schema](./doc/ERDv2.1.svg)** - Visual representation of database structure
+- **[Project Roadmap](./todo.md)** - Current tasks and future plans
 
 ## Development Workflow
 
-[Add development workflow instructions here] 
+### Daily Development Process
+
+1. **Pull Latest Changes**
+   ```bash
+   git pull origin main
+   npm install  # Update dependencies if needed
+   ```
+
+2. **Create Feature Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-description
+   ```
+
+3. **Development Cycle**
+   ```bash
+   # Start development server with Turbopack (faster)
+   npm run dev
+
+   # Run linter to check code quality
+   npm run lint
+
+   # Build to check for compilation errors
+   npm run build
+   ```
+
+4. **Database Changes**
+   ```bash
+   # Generate new migration after schema changes
+   npx drizzle-kit generate:pg
+
+   # Apply migrations
+   npx drizzle-kit push:pg
+   ```
+
+5. **Testing & Quality Assurance**
+   ```bash
+   # Lint your code
+   npm run lint
+
+   # Format code (if Prettier is configured)
+   npm run format
+
+   # Type check
+   npm run type-check
+   ```
+
+6. **Commit & Push**
+   ```bash
+   git add .
+   git commit -m "feat: add user authentication system"
+   git push origin feature/your-feature-name
+   ```
+
+### Useful Commands
+
+```bash
+# Development
+npm run dev          # Start dev server with Turbopack
+npm run build        # Build for production
+npm run start        # Start production server
+npm run lint         # Run ESLint
+
+# Database
+npx drizzle-kit studio              # Open Drizzle Studio (database GUI)
+npx drizzle-kit generate:pg         # Generate migrations
+npx drizzle-kit push:pg             # Apply schema changes
+npx drizzle-kit drop                # Drop database (destructive!)
+
+# Utilities
+npm run analyze      # Analyze bundle size (if configured)
+npm audit           # Check for security vulnerabilities
+```
+
+### Development Tools
+
+- **Database GUI**: Access Drizzle Studio at `http://localhost:4983` after running `npx drizzle-kit studio`
+- **API Testing**: Use the `.rest` files in `src/app/api/**/__tests__/` with REST client extensions
+- **Hot Reload**: Turbopack provides instant updates during development
+- **Type Safety**: TypeScript ensures compile-time error catching 

src/app/(admin-only)/create-training/page.tsx

@@ -4,6 +4,22 @@ import expectedBody from "../api/create-training/_expectedBody";
 import styles from './page.module.css';
 import { useState } from 'react';
 
+/**
+ * Admin page for creating new training programs
+ * 
+ * @description
+ * Provides a form interface for administrators to create new training programs.
+ * Includes form validation, submission handling, and user feedback.
+ * 
+ * Features:
+ * - Form validation using Zod schema
+ * - Loading state management during submission
+ * - Success/error feedback to users
+ * - Form reset after successful creation
+ * 
+ * @requires Admin authentication (enforced by route group)
+ * @returns JSX element containing the training creation form
+ */
 export default function Page() {
   const [isSubmitting, setIsSubmitting] = useState(false);
 
@@ -69,6 +85,23 @@ export default function Page() {
     </div>
   );
 
+  /**
+   * Handles form submission for creating a new training
+   * 
+   * @param event - Form submission event
+   * 
+   * @description
+   * Processes training creation form data through the following steps:
+   * 1. Prevents default form submission
+   * 2. Extracts and validates form data using Zod schema
+   * 3. Sends POST request to training creation API
+   * 4. Provides user feedback and resets form on success
+   * 5. Handles errors with appropriate user messaging
+   * 
+   * @todo Replace alert() calls with proper toast notifications
+   * @todo Add more specific error handling for different failure scenarios
+   * @todo Implement form field validation feedback
+   */
   async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
     event.preventDefault();
     setIsSubmitting(true);

src/app/(authorized-only)/trainings/page.tsx

@@ -6,6 +6,19 @@ import { mockAvailableTrainings } from "@/lib/mock/trainings";
 import { Input } from "@/components/ui/input";
 import { Search } from "lucide-react";
 
+/**
+ * Trainings page component for browsing and enrolling in available training programs
+ * 
+ * @description
+ * Displays a searchable list of available training programs with enrollment functionality.
+ * Features include:
+ * - Real-time search filtering by title and description
+ * - Responsive grid layout for training cards
+ * - Training enrollment handling
+ * - Empty state when no trainings match search criteria
+ * 
+ * @returns JSX element containing the trainings browse interface
+ */
 export default function TrainingsPage() {
   const [searchQuery, setSearchQuery] = useState("");
 
@@ -14,6 +27,14 @@ export default function TrainingsPage() {
     training.description.toLowerCase().includes(searchQuery.toLowerCase())
   );
 
+  /**
+   * Handles training enrollment for a user
+   * 
+   * @param trainingId - Unique identifier for the training program
+   * @todo Replace with actual API call to enrollment endpoint
+   * @todo Add error handling and user feedback
+   * @todo Implement enrollment status updates
+   */
   const handleEnroll = async (trainingId: string) => {
     // This will be replaced with actual API call later
     console.log(`Enrolling in training: ${trainingId}`);