Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
451 lines (338 loc) · 10.2 KB

SETUP_GUIDE.md

File metadata and controls

451 lines (338 loc) · 10.2 KB

Trinity Attend - Complete Setup & Implementation Guide

📋 Table of Contents

  1. Initial Setup
  2. Environment Variables
  3. Database Setup
  4. Installing Shadcn UI Components
  5. Authentication Implementation
  6. Dashboard Implementation
  7. QR Code System
  8. Geolocation Validation
  9. Deployment

1. Initial Setup

Step 1: Install Dependencies

cd c:\Users\HP\Desktop\trinity-attend
npm install

This will install all required packages including:

  • Next.js 16
  • React 19
  • Prisma
  • Better Auth
  • Shadcn UI dependencies
  • All other libraries

Step 2: Generate Secret Keys

Run these commands to generate secure keys:

# For AUTH_SECRET and BETTER_AUTH_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# For QR_CODE_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. Environment Variables

Required Variables (Must Configure):

  1. DATABASE_URL

    • Provider: Neon (Recommended)
    • Steps:
      1. Create account at neon.tech
      2. Create new project
      3. Copy connection string
      4. Format: postgresql://user:pass@host/db?sslmode=require

  2. AUTH_SECRET

    • Generate using the command above
    • Must be at least 32 characters

  3. QR_CODE_SECRET

    • Generate using the command above
    • Used for HMAC signing of QR codes

Optional Variables (Can Configure Later):

  1. GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET

  2. APPLE_CLIENT_ID & APPLE_CLIENT_SECRET

  3. RESEND_API_KEY

    • For sending emails
    • Get from: Resend

  4. CLOUDINARY Credentials

    • For profile picture uploads
    • Get from: Cloudinary

Example .env.local:

# Copy from .env.example and fill in your values
DATABASE_URL="postgresql://user:pass@ep-xxx.region.aws.neon.tech/trinity?sslmode=require"
AUTH_SECRET="generated-secret-key-here"
QR_CODE_SECRET="generated-qr-secret-here"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

3. Database Setup

Step 1: Push Schema to Database

npm run db:push

This creates all tables in your PostgreSQL database.

Step 2: Seed Database

npm run db:seed

This creates:

  • 3 Faculties (Science, Arts, Commercial)
  • 8 Departments (Computer Science, Nursing, etc.)
  • 20 Sample Courses (CSC 111, CSC 211, etc.)
  • 2 Demo Users (1 teacher, 1 student)

Step 3: Verify Data (Optional)

npm run db:studio

This opens Prisma Studio where you can view and edit your database.

4. Installing Shadcn UI Components

Shadcn UI components need to be installed individually. Here's how:

Initialize Shadcn UI (If Not Done):

npx shadcn@latest init

Install Required Components:

# Core UI Components
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add label
npx shadcn@latest add form
npx shadcn@latest add select
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add table
npx shadcn@latest add tabs
npx shadcn@latest add switch
npx shadcn@latest add progress
npx shadcn@latest add avatar
npx shadcn@latest add badge
npx shadcn@latest add separator
npx shadcn@latest add skeleton
npx shadcn@latest add checkbox
npx shadcn@latest add popover

# Toast Notifications (uses sonner, already configured)
# Already installed via package.json

These components will be added to src/components/ui/.

5. Authentication Implementation

Files Needed:

  1. Auth Routes:

    • src/app/api/auth/[...all]/route.ts - Better Auth handler
    • src/app/(auth)/layout.tsx - Auth pages layout
    • src/app/(auth)/role-selection/page.tsx - Choose Student/Teacher
    • src/app/(auth)/login/student/page.tsx - Student login
    • src/app/(auth)/login/teacher/page.tsx - Teacher login
    • src/app/(auth)/signup/student/page.tsx - Student signup
    • src/app/(auth)/signup/teacher/page.tsx - Teacher signup

  2. Server Actions:

    • src/actions/auth.actions.ts - Already created

Next Steps:

Run the app and test the landing page:

npm run dev

Visit http://localhost:3000

6. Dashboard Implementation

Student Dashboard Structure:

src/app/(dashboard)/student/
├── layout.tsx              # Student dashboard layout
├── page.tsx               # Home dashboard
├── courses/
│   ├── page.tsx           # Course list
│   └── [id]/page.tsx      # Course details
├── attendance/
│   ├── page.tsx           # Attendance overview
│   └── scan/page.tsx      # QR scanner
├── history/page.tsx       # Attendance history
├── profile/page.tsx       # Student profile
└── settings/page.tsx      # Settings

Teacher Dashboard Structure:

src/app/(dashboard)/teacher/
├── layout.tsx              # Teacher dashboard layout
├── page.tsx               # Home dashboard
├── courses/
│   ├── page.tsx           # Course list
│   ├── create/page.tsx    # Create course offering
│   └── [id]/
│       ├── page.tsx       # Course management
│       └── attendance/page.tsx  # Attendance table
├── analytics/page.tsx     # Analytics dashboard
└── settings/page.tsx      # Settings

7. QR Code System

QR Code Generation Flow (Teacher):

  1. Teacher selects course and week number
  2. System captures teacher's geolocation (latitude, longitude)
  3. Generate QR data: 
    {
  courseOfferingId: string,
  weekNumber: number,
  timestamp: number,
  expiresAt: number,
  latitude: number,     // Teacher's location
  longitude: number,    // Teacher's location
  signature: string     // HMAC-SHA256
}
  4. Display QR code valid for 10 minutes
  5. QR expires or teacher regenerates

QR Code Scanning Flow (Student):

  1. Student requests geolocation permission
  2. Student scans QR code
  3. System validates:
    • QR not expired
    • HMAC signature valid
    • Student enrolled in course
    • Student within 100m of teacher's location
  4. If all valid, mark attendance
  5. Show success/error message

Geolocation Validation Implementation:

// In src/lib/utils.ts (Already created)
export function calculateDistance(
  lat1: number, lon1: number,
  lat2: number, lon2: number
): number {
  // Haversine formula - returns distance in meters
}

export function isWithinAllowedRadius(
  userLat: number, userLon: number,
  targetLat: number, targetLon: number,
  maxDistanceMeters: number = 100
): boolean {
  const distance = calculateDistance(userLat, userLon, targetLat, targetLon);
  return distance <= maxDistanceMeters;
}

8. Geolocation Validation

Browser Geolocation API:

// Request user's location
navigator.geolocation.getCurrentPosition(
  (position) => {
    const latitude = position.coords.latitude;
    const longitude = position.coords.longitude;
    // Use for QR scanning or generation
  },
  (error) => {
    console.error("Geolocation error:", error);
  }
);

Security Considerations:

  1. HTTPS Required: Geolocation only works on HTTPS (or localhost)
  2. User Permission: Browser will ask for permission
  3. Accuracy: GPS accuracy varies (typically 5-50m)
  4. Timeout: Set reasonable timeout for location request
  5. Fallback: Handle cases where location is unavailable

Configuration:

In .env.local:

NEXT_PUBLIC_ENABLE_GEOLOCATION="true"
NEXT_PUBLIC_MAX_DISTANCE_METERS="100"

9. Deployment

Recommended Stack:

  • Hosting: Vercel (Next.js optimized)
  • Database: Neon (PostgreSQL)
  • File Storage: Cloudinary
  • Email: Resend

Deployment Steps:

  1. Push to GitHub

    git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main

  2. Deploy to Vercel

    • Go to vercel.com
    • Import your GitHub repository
    • Add environment variables
    • Deploy

  3. Configure OAuth Redirects

    • Update Google/Apple OAuth settings
    • Add production URLs

  4. Update Environment Variables

    • Set NEXT_PUBLIC_APP_URL to your production URL
    • Ensure all secrets are configured

10. Development Workflow

Daily Development:

# Start development server
npm run dev

# View database
npm run db:studio

# Push schema changes
npm run db:push

# Reseed database (if needed)
npm run db:seed

Before Deployment:

# Lint code
npm run lint

# Build for production
npm run build

# Test production build
npm run start

11. Troubleshooting

Common Issues:

  1. Module not found errors

    rm -rf node_modules package-lock.json
npm install

  2. Prisma Client errors

    npx prisma generate
npm run db:push

  3. Type errors

    • Restart TypeScript server in VS Code
    • Run npx prisma generate

  4. Database connection errors

    • Check DATABASE_URL in .env.local
    • Ensure database is running
    • Verify SSL mode is correct

12. Next Implementation Steps

Priority Order:

  1. ✅ Setup Complete (You are here)
  2. Week 1: Authentication pages (login/signup)
  3. Week 2: Student dashboard and course enrollment
  4. Week 3: Teacher dashboard and course management
  5. Week 4: QR code system with geolocation
  6. Week 5: Analytics and reporting
  7. Week 6: Excel/PDF export
  8. Week 7: Testing and deployment

📞 Need Help?

  • Check the README.md for setup instructions
  • Review the code comments for implementation details
  • Open an issue on GitHub
  • Email: support@trinityattend.com

Your Trinity Attend project is now set up and ready for development! 🎉

Next step: Run npm run dev and visit http://localhost:3000 to see your landing page.