Witelli20 Student Portal

A modern, responsive web application for the Witellikerstrasse 20 student housing community in Zurich. Built with Next.js 15, React 19, Firebase, and Tailwind CSS, featuring real-time transport information, room reservations, community message boards, and weather integration.

Features

Core Functionality

• Room Reservations - Book common spaces (Foyer, Party Room) with calendar view
• Transport Information - Real-time departures and schedules using Swiss Transport API
• Lost & Found - System for tracking missing items and packages
• Community Board - Anonymous confession board for student communications
• Weather Integration - Local weather forecasts and conditions

Technical Highlights

• Server-side rendering with Next.js 15 App Router
• Real-time database with Firebase Firestore
• Responsive design with Tailwind CSS
• Smooth animations using Framer Motion
• Modern React 19 features
• TypeScript for type safety
• Automated release management

Tech Stack

Frontend

• Framework: Next.js 15.4.8 with App Router
• UI Library: React 19.1.1
• Styling: Tailwind CSS 3.4 with Typography plugin
• Animations: Framer Motion 12
• Icons: Phosphor Icons, Heroicons
• Markdown: React Markdown with GFM support
• Animations: Lottie via @lottiefiles/dotlottie-react

Backend & Services

• Database: Firebase Firestore
• APIs: Swiss Transport API, Weather API
• HTTP Client: Axios 1.11
• Date Handling: date-fns 4.1

Development

• Language: TypeScript 5
• Linting: ESLint 9 with Next.js config
• Build Tool: Next.js with Turbopack (dev mode)
• Package Manager: npm
• Node Version: 20.x or later

Getting Started

Prerequisites

• Node.js 20.x or later
• npm or yarn
• Firebase account (for database and authentication)

Installation

1. Clone the repository

   git clone https://github.com/peaktwilight/witelli20.git
   cd witelli20

2. Install dependencies

   npm install
   # or
   yarn install

3. Configure environment variables

   Copy .env.example to .env.local:

   cp .env.example .env.local

   Then edit .env.local with your Firebase configuration:

   NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
   NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
   NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
   NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
   NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
   NEXT_PUBLIC_APP_VERSION=0.1.0

4. Start the development server

   npm run dev
   # or
   yarn dev

5. Open your browser

   Navigate to http://localhost:3000

Available Scripts

• npm run dev - Start development server with Turbopack
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run ESLint
• npm run migrate-messages - Run message migration script
• npm run release - Automated release (version bump, tag, push)

Project Structure

witelli20/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/               # API route handlers
│   │   ├── board/             # Community message board
│   │   ├── reservations/      # Room reservation system
│   │   ├── stolen/            # Lost & found tracker
│   │   ├── transport/         # Transport information
│   │   ├── weather/           # Weather forecast
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Home page
│   │   └── globals.css        # Global styles
│   ├── components/            # Reusable React components
│   │   ├── FAQ.tsx
│   │   ├── QuickLinks.tsx
│   │   ├── WeatherWidget.tsx
│   │   └── ...
│   ├── hooks/                 # Custom React hooks
│   ├── lib/                   # Utilities and API clients
│   │   ├── firebase.ts        # Firebase configuration
│   │   ├── transportApi.ts    # Swiss Transport API
│   │   └── weatherApi.ts      # Weather API integration
│   └── types/                 # TypeScript type definitions
├── public/                    # Static assets
├── scripts/                   # Build and deployment scripts
├── .github/                   # GitHub Actions workflows
│   └── workflows/
│       ├── ci.yml            # Continuous integration
│       └── release.yml       # Release automation
├── firebase.json              # Firebase configuration
├── firestore.rules            # Firestore security rules
├── firestore.indexes.json     # Firestore indexes
├── next.config.ts             # Next.js configuration
├── tailwind.config.ts         # Tailwind CSS configuration
└── tsconfig.json              # TypeScript configuration

Environment Variables

The application requires the following environment variables in .env.local:

Variable	Description	Required
NEXT_PUBLIC_FIREBASE_API_KEY	Firebase API key	Yes
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN	Firebase auth domain	Yes
NEXT_PUBLIC_FIREBASE_PROJECT_ID	Firebase project ID	Yes
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET	Firebase storage bucket	Yes
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID	Firebase messaging sender ID	Yes
NEXT_PUBLIC_FIREBASE_APP_ID	Firebase app ID	Yes
NEXT_PUBLIC_APP_VERSION	Application version	No

Note: The Swiss Transport API used in the project does not require authentication.

Deployment

Vercel (Recommended)

The easiest way to deploy this Next.js application:

1. Push your code to GitHub
2. Import your repository on Vercel
3. Configure environment variables in project settings
4. Deploy - Vercel will automatically build and deploy on every push to main

Firebase Hosting

Alternative deployment option using Firebase:

1. Install Firebase CLI

   npm install -g firebase-tools

2. Login to Firebase

   firebase login

3. Initialize Firebase (if not already done)

   firebase init

   • Select Hosting and Firestore
   • Choose your Firebase project
   • Set build as the public directory

4. Build and deploy

   npm run build
   firebase deploy

Other Platforms

This Next.js application can be deployed to any platform that supports Node.js:

• Netlify
• Railway
• Render
• AWS Amplify

Release Management

Automated Release

The project includes automated release management:

npm run release

This will:

• Bump the patch version in package.json
• Update version in .env.local
• Create a git tag
• Push changes and tags to GitHub
• Trigger GitHub Actions to create a release

Manual Release

For more control over versioning:

# Bump version (patch, minor, or major)
npm version patch

# Push with tags
git push --follow-tags

# Or create release with GitHub CLI
gh release create v0.1.x --title "Release v0.1.x" --notes "Release notes"

View all releases: GitHub Releases

Contributing

This is an open source project and contributions are welcome! Whether you want to:

• Fix bugs
• Add new features
• Improve documentation
• Suggest ideas

Your contributions are appreciated.

How to Contribute

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
4. Commit with descriptive messages

   git commit -m "Add: brief description of changes"

5. Push to your fork

   git push origin feature/your-feature-name

6. Open a Pull Request

Please read CONTRIBUTING.md for detailed guidelines.

Code of Conduct

Please be respectful and constructive in all interactions. This project follows standard open source community guidelines.

Documentation

• Next.js Documentation
• React Documentation
• Firebase Documentation
• Tailwind CSS Documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for the student community at Witellikerstrasse 20, Zurich
• Uses the Swiss Transport API for real-time transport data
• Icons by Phosphor Icons and Heroicons
• Animations by Lottie

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check existing issues and discussions
• Review the FAQ section on the live site

---

Built by Doruk