🔍 Facfyndr

Part of Project Harukaze🍃

Overview

A community-driven faculty directory developed to help students easily find and connect with faculty members at BUBT

🌟 Features

• Progressive Web App (PWA) Support:
  Enhanced user experience with offline functionality, installability, and native app-like performance.

• Effortless Search:
  Find faculty members in seconds by searching for their name, faculty code, or email.

• QR Code Magic:
  Generate QR codes for faculty profiles – perfect for networking events or quick sharing.

• vCard Downloads:
  Save faculty contact details directly to your phone with a single click.

• Report Incorrect Info:
  Help us keep the directory accurate by reporting incorrect information with just a few clicks.

• Minimalist Design:
  Clean, modern, and distraction-free. Built to work seamlessly on devices.

• Admin Dashboard (Coming Soon):
  A powerful dashboard to manage user reports, faculty data, update information, and ensure the directory stays up-to-date.

🧩 Project Structure

The repository is organized into two main folders, each representing a core part of the project:

• App (SvelteKit)

  The app folder contains the fully functional SvelteKit application, including the UI and server-side logics.

• Admin (Database Management)

  The admin folder is used to prepare and manage the database. Faculty member data is initially fetched using BUBT Faculty Scrapper and processed here. It also includes plans for an admin dashboard to manage the database.

🛠️ Installation

Before you begin, ensure you have the followings:

• pnpm (v10.6.2 or later)
• Node.js (v22.14.0 LTS or later)
• Supabase Account - For the database
• Cloudflare Account - For the turnstile (captcha)

The repository is divided into two main sections: app (frontend) and admin (data processing).

1. Setting Up the App (Frontend)

1. Clone the repository:

   git clone https://github.com/kurtnettle/facfyndr.git

2. Navigate to the app folder:

   cd facfyndr/app

3. Install dependencies:

   pnpm install

4. Set up environment variables:

   Rename the a .env.example to .env file in the app folder and add the following values:

   DATABASE_URL=""
   TURNSTILE_SECRET_KEY=""
   PUBLIC_TURNSTILE_SITE_KEY=""

5. Run the development server:

   pnpm run dev

2. Setting Up the Admin (Data Processing)

Note

Under Development.

🛠️ Tech Stack

Frontend

• SvelteKit: A modern framework for building fast, reactive web apps with built-in server-side rendering (SSR) and API routes.
• Tailwind CSS: A utility-first CSS framework for rapid UI development.
• Superforms: A powerful SvelteKit form library for seamless form handling and validation.
• Lucide Svelte: A beautiful, community-driven open-source icon library.
• Shadcn Svelte: Elegantly designed UI components for building modern interfaces.
• Svelte Turnstile: Easy integration with Cloudflare Turnstile for bot detection.

Backend & Data Management

• Supabase: An open-source Firebase alternative for database and authentication.
• Drizzle ORM: A TypeScript ORM for managing database interactions.
• Zod: TypeScript-first schema validation for forms and APIs.
• BUBT Faculty Scraper: A custom tool for fetching faculty data from university website.

Utility Libraries

• @svelte-put/qr: For generating QR codes with ease.
• vcard-creator: A JavaScript vCard creator library.

💬 Support

Need help or want to discuss issues? Join our Telegram group

🤝 Contributing

Contributions are welcome! If you'd like to improve the tool or fix bugs, feel free to submit a pull request. Please ensure your changes align with the project's coding standards.

📜 License

This project is licensed under the GPLv3 License. See the LICENSE file for full details.

By contributing to this project, you agree that your contributions will be licensed under the GPLv3 License as well.

💌 Acknowledgments

This project wouldn’t have been possible without the incredible work of the open-source community.