VESITRail

Streamlined Railway Concessions with Real-time Tracking

A modern web application for VESIT students to apply and manage railway concessions with ease

• 🎓 Easy Application Process - Apply for railway concessions with auto-filled details
• 📊 Real-time Tracking - Monitor application status with live updates
• 🏠 Address Management - Update home station and address details seamlessly
• 📱 Progressive Web App - Install and use offline with native app experience
• 🔔 Smart Notifications - Get push notifications about application updates
• 📋 Application History - View past applications and their status
• 📄 Digital Booklets - Download digital concession booklets

• 👥 Student Management - Review and approve student registrations
• 📝 Application Processing - Efficiently handle concession applications
• 📈 Analytics Dashboard - Track applications and generate reports
• 🎫 Booklet Management - Generate and manage concession booklets
• 📊 Comprehensive Reports - Generate detailed analytics and insights
• 🔄 Address Change Requests - Process student address change requests

• ⚡ Lightning Fast - Optimized performance with Next.js 15
• 🎨 Modern UI/UX - Beautiful interface with Radix UI components
• 🔐 Secure Authentication - Google OAuth with Better Auth
• 📱 Fully Responsive - Works perfectly on all devices
• 🌙 Dark Mode Support - Toggle between light and dark themes
• 🔄 Real-time Updates - Live status updates and push notifications
• 📊 Analytics - PostHog integration for insights

Frontend
Backend
Database
UI Components
File Upload & PDF
Notifications
Testing

The easiest way to get started is using the DevContainer, which provides a fully configured development environment.

Prerequisites:

• Docker Desktop or Docker Engine
• Visual Studio Code with Dev Containers extension

Steps:

1. Open the project in VS Code
2. Click "Reopen in Container" when prompted, or use Command Palette: Dev Containers: Reopen in Container
3. Wait for the container to build and dependencies to install
4. Copy environment variables: cp .devcontainer/.env.devcontainer .env
5. Update .env with your API credentials
6. Run database migrations: npx prisma migrate dev
7. Start the development server: npm run dev

See .devcontainer/README.md for more details.

Prerequisites:

• Node.js 18+ and npm
• PostgreSQL database
• Google OAuth credentials
• Cloudinary account (for file uploads)
• Firebase project (for push notifications)

Installation:

1. Clone the repository

   git clone https://github.com/jaykerkar0405/vesitrail.git
   cd vesitrail

2. Install dependencies

   npm ci

3. Environment Setup

   cp .env.example .env

   Fill in your environment variables:

   # Site Configuration
   NEXT_PUBLIC_SITE_URL="http://localhost:3000"
   
   # BetterAuth
   BETTER_AUTH_URL="http://localhost:3000"
   BETTER_AUTH_SECRET="your-32-character-secret-key"
   
   # Database
   DATABASE_URL="postgresql://username:password@localhost:5432/vesitrail"
   
   # Google OAuth
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   NEXT_PUBLIC_GOOGLE_CLIENT_ID="your-google-client-id"
   
   # Cloudinary
   NEXT_PUBLIC_CLOUDINARY_API_KEY="your-api-key"
   NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your-cloud-name"
   CLOUDINARY_API_SECRET="your-api-secret"
   
   # Firebase (Push Notifications)
   NEXT_PUBLIC_FIREBASE_PROJECT_ID="your-project-id"
   NEXT_PUBLIC_FIREBASE_API_KEY="your-api-key"
   # ... other Firebase config

4. Database Setup

   npx prisma generate
   npx prisma db push

5. Run the development server

   npm run dev

6. Open your browser

   Navigate to http://localhost:3000

For detailed architectural information, system design, and technical specifications, see ARCHITECTURE.md.

src/
├── app/                    # Next.js App Router
│   ├── (routes)/          # Route groups
│   │   └── dashboard/     # Dashboard routes
│   ├── globals.css        # Global styles
│   └── manifest.ts        # PWA manifest
├── components/            # Reusable UI components
│   ├── ui/               # shadcn/ui components
│   ├── layout/           # Layout components
│   ├── onboarding/       # Onboarding flow
│   ├── student/          # Student-specific components
│   └── admin/            # Admin-specific components
├── lib/                   # Utility libraries
├── actions/              # Server actions
├── hooks/                # Custom React hooks
├── config/               # Configuration files
└── generated/            # Generated types and schemas

Students complete a multi-step onboarding process:

• Personal information
• Academic details
• Travel preferences
• Document verification
• Profile review

• Auto-filled forms based on student profile
• Support for new and renewal applications
• Real-time status tracking
• Document upload with Cloudinary

• Station-based address updates
• Admin approval workflow
• Document verification requirements

• Student registration approval
• Application processing
• Booklet management
• Analytics and reporting

• Firebase Cloud Messaging integration
• Real-time application status updates
• Cross-platform notification support
• Customizable notification preferences

VESITRail uses a comprehensive design system built with:

• Color Palette: Custom CSS variables for consistent theming
• Typography: Inter font family with responsive scaling
• Components: shadcn/ui with custom variants
• Icons: Lucide React for consistent iconography
• Responsive Design: Mobile-first approach with Tailwind CSS

// Light and dark mode support
const { theme, setTheme } = useTheme();

// Toggle theme
<Button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>{theme === "dark" ? <Sun /> : <Moon />}</Button>;

VESITRail is a fully-featured PWA with:

• 📱 Installable - Add to home screen on mobile devices
• ⚡ Fast Loading - Optimized performance and caching
• 🔄 Offline Support - Basic functionality works offline
• 📸 App Screenshots - Rich install prompts with screenshots
• 🎯 Native Feel - App-like experience across platforms
• 🔔 Push Notifications - Firebase-powered notifications

• Authentication: Secure Google OAuth integration
• Authorization: Role-based access control (Student/Admin)
• Data Validation: Comprehensive input validation with Zod
• File Upload: Secure document upload with Cloudinary
• Email Verification: @ves.ac.in domain restriction
• CSRF Protection: Built-in security measures
• Database Security: PostgreSQL with SSL connections

1. Connect your repository to Vercel
2. Configure environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

# Build the application
npm run build

# Start production server
npm start

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• TypeScript: Strict mode enabled
• ESLint: Custom configuration for Next.js
• Prettier: Consistent code formatting
• Conventional Commits: Semantic commit messages

VESITRail uses Playwright for end-to-end testing to ensure application reliability across browsers.

# Install Playwright browsers (first time only)
npm run test:e2e:install

# Run E2E tests
npm run test:e2e

# Run tests in UI mode (interactive)
npx playwright test --ui

# Run tests in headed mode (see browser)
npx playwright test --headed

Test Configuration:

• Test files: Place E2E tests in tests/ directory with .spec.ts extension
• Browsers: Tests run on Chromium, Firefox, and WebKit
• CI/CD: Automatically runs on pull requests
• Reports: HTML test reports generated after test runs

For more on writing tests, see the Playwright documentation.

This project is released under the VESITRail Community License v1.0 (custom, source-available, restricted deployment). Only Vivekanand Education Society's Institute of Technology (VESIT) is authorized to deploy operational instances. External contributors are welcome to submit improvements under the same license.

• License: See LICENSE
• Contributing: See CONTRIBUTING.md
• Code of Conduct: See CODE_OF_CONDUCT.md
• Security Policy: See SECURITY.md

If you need a different license arrangement or deployment permission, open a discussion or contact the maintainer privately.