Welcome to GDSC Farmingdale Links, your dynamic portal for staying connected with all things GDSC Farmingdale! This application serves as a central hub, aggregating and presenting real-time event information and essential resources from dedicated APIs through an intuitive and interactive user interface.

Navigate through this documentation with ease:

• 1. Overview & Introduction
  • Purpose & Goals
  • Problem Solved
  • Target Audience
• 2. Feature Highlights
• 3. Architecture & Design
  • High-Level Component Diagram
  • Core Modules & Responsibilities
  • Technology Stack
• 4. Getting Started
  • Prerequisites
  • Installation Steps
  • Configuration
  • Running the Application
• 5. Usage & Workflows
  • Browsing Events
  • Authentication
  • Search & Navigation
  • Common CLI Commands
• 6. Limitations, Known Issues & Future Roadmap
  • Current Limitations
  • Known Issues
  • Future Roadmap
• 7. Contributing & Development Guidelines
  • How to Contribute
  • Branching & PR Guidelines
  • Code Style & Quality
  • Testing
  • Development Setup
• 8. License, Credits & Contact
  • License
  • Acknowledgements
  • Contact
• 9. Appendix
  • Changelog
  • Frequently Asked Questions (FAQ)
  • Troubleshooting Guide
  • API References

The GDSC Farmingdale Links application acts as the official frontend for the Google Developer Student Clubs (GDSC) chapter at Farmingdale State College. It's designed to provide students, faculty, and interested community members with effortless access to upcoming events, past activities, and relevant resources.

Our primary goals with this application are:

• Centralization: Create a single, easy-to-access platform for all GDSC Farmingdale-related information.
• Engagement: Foster greater participation in events and community activities by making information readily available and engaging.
• Accessibility: Ensure the application is responsive and usable across various devices and platforms.
• Modern Experience: Deliver a smooth, interactive, and visually appealing user experience using cutting-edge web technologies.

In a vibrant academic community, information about events, workshops, and opportunities can often be scattered across multiple platforms. This leads to missed opportunities and reduced engagement. GDSC Farmingdale Links solves this by:

• Aggregating event data from dedicated, reliable APIs.
• Providing a consistent, user-friendly interface for browsing.
• Enabling quick access to event details, resources, and sign-up links.

This application is built for:

• Current GDSC Farmingdale Members: To easily track upcoming meetings, workshops, and social events.
• Prospective Members: To discover GDSC activities and learn how to get involved.
• Farmingdale State College Students & Faculty: To stay informed about technology-related events and opportunities on campus.
• Community Members: Anyone interested in GDSC initiatives and tech-related learning.

⬆️ Back to Top

This application is packed with features designed to enhance your experience:

• ✅ Dynamic Event Listing: Fetches and displays the latest GDSC Farmingdale events, past events, and general links in real-time from our dedicated backend APIs.
• 🔍 Intuitive Search & Filter: Easily find specific events or resources using the integrated search functionality.
• 🌐 Responsive & Adaptive UI: Crafted with React, Vite, and TypeScript, ensuring a seamless experience across desktops, tablets, and mobile devices.
• 🎨 Modern Design System: Utilizes Shadcn UI and NextUI for a consistent, visually appealing, and accessible user interface, complemented by Tailwind CSS for utility-first styling.
• ✨ Interactive Animations: Enhanced user experience with smooth transitions and animations powered by Framer Motion, including background gradients and confetti effects.
• 🔐 Secure Authentication: Supports seamless authentication via Firebase, offering both anonymous and Google sign-in options.
• 🚀 Performance-Optimized: Leverages Vite for lightning-fast development and optimized production builds, ensuring quick load times.
• 🖼️ Rich Media Experience: Features customizable image and video carousels, supporting embedded content and local assets for engaging presentations.
• 📊 Analytics Integration: Integrates Google Analytics, Search Console, and Tag Manager to monitor user activity and improve service delivery.
• ⚙️ Containerized Deployment: Provided with a Dockerfile and compose.yaml for easy, consistent, and scalable deployment using Docker.
• 💡 Dark Mode Support: Switch between light and dark themes for optimal viewing comfort and accessibility.
• 🍪 GDPR/CCPA Cookie Consent: Built-in mechanism for managing user consent for cookies.
• 🧩 Interactive Mini-Games: Includes a fun Tic-Tac-Toe game component for user engagement.
• 🔗 Copy-to-Clipboard & Share Functionality: Easily share event links or other content directly from the UI.

⬆️ Back to Top

The GDSC Farmingdale Links application is a client-side React application that interacts with several external services to provide its functionality. It follows a modular design pattern to ensure maintainability and scalability.

The following diagram illustrates the primary components of the GDSC Farmingdale Links frontend application and its interaction with external services:

graph TD
    subgraph Client_GDSC_Farmingdale_Links_Frontend
        A[User Interface React Shadcn UI NextUI] --> B[Routing and Pages - events links contact]
        B --> C[Core Components - Auth Search Media Layouts]
        C --> D[State Management - Zustand Context API]
        D --> E[Data Fetching and Transformation]
    end

    subgraph Backend_Services
        F[GDSC Events API]
        G[GDSC Links API]
        H[Contact Form Service]
    end

    subgraph External_Infrastructure
        I[Firebase Authentication]
        J[Firebase Hosting]
        K[Google Analytics Tag Manager]
    end

    E --> F
    E --> G
    C --> H
    A --> I
    A --> J
    A --> K

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#ccf,stroke:#333,stroke-width:2px
    style D fill:#ddf,stroke:#333,stroke-width:2px
    style E fill:#eef,stroke:#333,stroke-width:2px
    style F fill:#cfc,stroke:#333,stroke-width:2px
    style G fill:#cfc,stroke:#333,stroke-width:2px
    style H fill:#cfc,stroke:#333,stroke-width:2px
    style I fill:#fcc,stroke:#333,stroke-width:2px
    style J fill:#fcc,stroke:#333,stroke-width:2px
    style K fill:#fcc,stroke:#333,stroke-width:2px

The application's codebase is structured into logical modules, each with distinct responsibilities:

• src/app/: Contains core application logic, server-side components (for data fetching in a React context), and UI wrappers for data display.
  • src/app/server: Simulates backend API calls for Links, PastEvents, UpcomingEvents.
  • src/app/ui: Wrappers for content display, tabs, and sections.
• src/components/: Houses reusable UI components, grouped by functionality.
  • animation: Provides interactive visual elements like BackgroundGradientAnimation and Confetti.
  • auth: Handles user authentication flow and displays user status.
  • custom: Generic, custom-built components like Button, Card, Media, Settings, Hint, etc.
  • dom: Fallback components for loading, 404, and error states.
  • form: Form-related components for input, errors, and submission.
  • game: Interactive game components (e.g., Tic-Tac-Toe).
  • icons: A collection of SVG icons used throughout the application.
  • layouts: Defines various container and page layouts.
  • providers: Context providers for global state management (e.g., Carousel, Error Handling, Theme).
  • search: Components related to search functionality.
  • templates: Reusable structural and semantic components.
  • ui: Integrates and extends components from Shadcn UI (e.g., button, dialog, tabs, tooltip).
• src/constants/: Stores static data, configuration, and literal values used across the app.
• src/core/: Critical application logic such as Firebase initialization, authentication, and global state.
• src/data/: Configuration files (e.g., config.ts).
• src/hooks/: Custom React hooks for encapsulating reusable logic (e.g., useCopyToClipboard, useOnlineStatus).
• src/lib/: Utility functions (e.g., utils.ts).
• src/routes/: Defines the different pages and their components (e.g., index.tsx, contact.tsx, login.tsx).
• src/schema/: Zod schemas for input validation (e.g., contact form).
• src/styles/: Global CSS and CSS variables.
• src/types/: TypeScript type definitions for both frontend and backend data structures.
• src/utils/: General utility functions for various tasks (e.g., cookies, blurHash, minimax for games).

• Frontend Framework: React (v18+)
• Build Tool: Vite (v5+)
• Language: TypeScript (v5+)
• Styling:
  • Tailwind CSS (v3+) for utility-first CSS.
  • Shadcn UI for beautifully designed and accessible components.
  • NextUI for additional modern UI components.
  • PostCSS for CSS transformations.
• State Management: React Context API and potentially Zustand (if src/core/store.ts implies it) for global state.
• Authentication: Firebase Authentication
• Animations: Framer Motion
• Routing: React Router DOM (inferred from common React patterns, not explicitly in file structure but typical)
• Linting & Formatting: Biome
• Testing: Vitest (Unit and E2E testing)
• Containerization: Docker
• Deployment: Firebase Hosting
• Analytics: Google Analytics, Google Tag Manager, Google Search Console

⬆️ Back to Top

Follow these steps to get GDSC Farmingdale Links up and running on your local machine.

Before you begin, ensure you have the following installed:

• Git: For cloning the repository.
  • Download Git
• Node.js: Version 18.x or higher.
  • Download Node.js
• npm or Yarn: Package managers, typically bundled with Node.js.
  • npm (Node Package Manager) - comes with Node.js
  • yarn (Optional) - npm install -g yarn
• Docker & Docker Compose (Optional, for containerized development/deployment)
  • Download Docker Desktop

1. Clone the Repository: Start by cloning the project to your local machine:

   git clone https://github.com/GDSC-FSC/gdsc-farmingdale-links.git
   cd gdsc-farmingdale-links

2. Install Dependencies: Use your preferred package manager to install the project dependencies:

   # Using npm
   npm install
   
   # Or using Yarn
   yarn install

3. Install Biome (Globally Recommended): For consistent code formatting and linting, it's recommended to install Biome globally:

   npm install -g @biomejs/biome

The application relies on environment variables for sensitive information and service API keys.

1. Create Environment File: Duplicate the .env.example file and rename it to .env.local:

   cp .env.example .env.local

2. Populate Environment Variables: Open .env.local and fill in the necessary values. These typically include Firebase configuration and potentially API keys for any external services (like the event backend APIs).

   # Example .env.local content
   VITE_FIREBASE_API_KEY="YOUR_FIREBASE_API_KEY"
   VITE_FIREBASE_AUTH_DOMAIN="YOUR_FIREBASE_AUTH_DOMAIN"
   VITE_FIREBASE_PROJECT_ID="YOUR_FIREBASE_PROJECT_ID"
   VITE_FIREBASE_STORAGE_BUCKET="YOUR_FIREBASE_STORAGE_BUCKET"
   VITE_FIREBASE_MESSAGING_SENDER_ID="YOUR_FIREBASE_MESSAGING_SENDER_ID"
   VITE_FIREBASE_APP_ID="YOUR_FIREBASE_APP_ID"
   VITE_FIREBASE_MEASUREMENT_ID="YOUR_FIREBASE_MEASUREMENT_ID"
   VITE_FIREBASE_CLIENT_EMAIL="YOUR_FIREBASE_CLIENT_EMAIL" # Optional, for server-side auth
   VITE_FIREBASE_PRIVATE_KEY="YOUR_FIREBASE_PRIVATE_KEY" # Optional, for server-side auth
   
   VITE_GDSC_EVENTS_API_URL="https://api.example.com/gdsc-events" # Placeholder
   VITE_GDSC_LINKS_API_URL="https://api.example.com/gdsc-links" # Placeholder
   VITE_CONTACT_FORM_API_URL="https://api.example.com/contact" # Placeholder

   ⚠️ Important: Never commit your .env.local file to version control. It's already ignored by .gitignore.

To run the application in development mode with hot-reloading:

npm run dev
# Or with Yarn:
yarn dev

This will typically start the application on http://localhost:5173 (or another available port).

To create a production-optimized build:

npm run build
# Or with Yarn:
yarn build

This command compiles the application into the dist/ directory.

After building, you can serve the production build locally to test it:

npm run preview
# Or with Yarn:
yarn preview

For a containerized environment, you can use Docker:

1. Build the Docker Image:

   docker build -t gdsc-farmingdale-links:latest .

2. Run the Docker Container:

   docker run -p 80:80 gdsc-farmingdale-links:latest

   The application will then be accessible at http://localhost:80.

3. Using Docker Compose: If you have compose.yaml configured for additional services (e.g., a local backend API), you can spin up the entire stack:

   docker compose up -d

⬆️ Back to Top

GDSC Farmingdale Links is designed for intuitive navigation and information retrieval.

The core functionality revolves around displaying upcoming and past events.

1. Home Page (/): Upon visiting the application, you'll be greeted with a concise overview of the GDSC, often featuring upcoming events or important announcements.
2. Upcoming Events: Navigate to the "Events" section to see a chronological list of all planned GDSC activities. Each event card provides a summary, date, and typically a link for more details or registration.
   • Example Interaction:

     sequenceDiagram
         participant User
         participant Frontend
         participant EventsAPI
     
         User->>Frontend: Access Home Page
         Frontend->>EventsAPI: Request Upcoming Events
         EventsAPI-->>Frontend: Returns Event Data
         Frontend->>User: Displays Events (e.g., "Tech Talk: AI Trends", "Workshop: Intro to React")
         User->>Frontend: Clicks on "Tech Talk" event
         Frontend->>User: Displays Event Details Page
     

     Loading
3. Past Events: A dedicated section allows you to browse through previous GDSC activities, often with photos or summaries of what happened. This is great for new members to see the club's history.
4. Links/Resources: Find important external links, social media profiles, or general GDSC resources.

The application offers a streamlined authentication process using Firebase.

1. Login Button: Look for a "Login" or "Sign In" button, usually in the header or a dedicated authentication section.

2. Google Sign-In: The primary authentication method is via Google, providing a quick and familiar experience.

3. Anonymous Login: For users who want to browse without a full sign-up, an anonymous login option might be available, offering limited functionality (e.g., not saving preferences).

   sequenceDiagram
       participant User
       participant Frontend
       participant FirebaseAuth
   
       User->>Frontend: Clicks "Login"
       Frontend->>User: Presents Login Options (e.g., "Sign in with Google", "Continue Anonymously")
       User->>Frontend: Selects "Sign in with Google"
       Frontend->>FirebaseAuth: Initiates Google Auth Flow
       FirebaseAuth-->>User: Prompts for Google Account Access
       User-->>FirebaseAuth: Grants Access
       FirebaseAuth-->>Frontend: Returns User Token/Info
       Frontend->>User: Displays Logged-in State (e.g., User avatar, "Logout" button)
   

   Loading

• Search Bar: Utilize the prominent search bar to quickly find events, resources, or specific information by keywords.
• Categories/Tags: Events may be categorized or tagged, allowing you to filter by topics like "AI," "Web Development," or "Social Event."
• Responsive Navigation: The navigation menu adapts to your screen size, providing a hamburger menu on smaller devices.

Beyond development, these commands are useful for maintenance and quality assurance:

• Run Development Server:

  npm run dev

  Starts the local development server.

• Build for Production:

  npm run build

  Creates an optimized production build in the dist/ directory.

• Preview Production Build:

  npm run preview

  Serves the static production build locally for testing.

• Run Unit Tests:

  npm test # or npm run test:unit

  Executes all unit tests.

• Run End-to-End Tests:

  npm run test:e2e

  Executes end-to-end tests (requires a running application instance).

• Lint and Format Code with Biome:

  npm run lint
  npm run format
  # Or to fix issues automatically:
  npm run lint:fix
  npm run format:fix

  Ensures code quality and consistency across the project.

⬆️ Back to Top

Understanding the current state and future direction of the project is crucial.

• API Dependency: The application heavily relies on external APIs for event data. If these APIs are down or slow, the application's content may be affected.
• Static Content Management: While some content is dynamic via APIs, certain static content (like images, descriptions not from APIs) requires code changes to update.
• No Offline Support (PWA limited): Although a manifest.json exists, full offline capabilities (e.g., service workers for caching dynamic content) are not yet fully implemented.
• Administrator Dashboard: Currently, there is no integrated admin interface for managing events, users, or content directly within the application. Changes typically require API updates or direct database manipulation for the backend.
• Localization: The application is currently designed for a single language (English), without built-in localization support for other languages.

• Carousel Autoplay sometimes stops: In certain browser/device combinations, the ImageCarousel or VideoCarousel might occasionally pause its autoplay feature unexpectedly. A refresh typically resolves this.
• Initial Load Performance (Large Media): On slower network connections, pages with numerous high-resolution images or videos might experience a slightly longer initial load time before optimizations like blur hashes fully kick in.
• Accessibility (ARAI Compliance): While efforts have been made, some complex interactive components might not fully adhere to the highest WCAG/ARIA standards across all screen readers or assistive technologies. (Ongoing improvement).

Our vision for GDSC Farmingdale Links includes:

• Full PWA Implementation: Enhance offline capabilities, push notifications for upcoming events, and "Add to Home Screen" prompt for a native app-like experience.
• Admin Dashboard: Develop a secure, user-friendly interface for GDSC organizers to manage events, resources, and user roles directly.
• User Personalization: Allow authenticated users to save favorite events, set reminders, and receive personalized content recommendations.
• Advanced Filtering & Sorting: Implement more robust filtering options (e.g., by date range, topic, speaker) and sorting capabilities for events.
• Community Features: Integrate features like event comments, discussion forums, or direct messaging with event organizers.
• i18n (Internationalization): Support multiple languages to cater to a diverse student body.
• Improved Accessibility: Continuous auditing and improvement of accessibility features to ensure WCAG 2.1 AA compliance.
• Backend Integration for Contact Form: Fully integrate src/schema/contact.ts with a functional backend service to process and store contact inquiries.
• Enhanced Search: Implement fuzzy searching and faceted search capabilities.

⬆️ Back to Top

We welcome contributions from everyone! Whether it's reporting a bug, suggesting a feature, or submitting code, your help is valuable.

1. Fork the Repository: Start by forking the gdsc-farmingdale-links repository to your GitHub account.
2. Clone Your Fork: Clone your forked repository to your local machine:

   git clone https://github.com/YOUR_USERNAME/gdsc-farmingdale-links.git
   cd gdsc-farmingdale-links

3. Create a New Branch: Always create a new branch for your work. Use a descriptive name:

   git checkout -b feature/your-new-feature
   # or
   git checkout -b bugfix/fix-login-issue

4. Make Your Changes: Implement your feature or bug fix.
5. Commit Your Changes: Write clear, concise commit messages.

   git commit -m "feat: Add new event filtering option"
   # or
   git commit -m "fix: Resolve issue with carousel autoplay"

6. Push to Your Fork:

   git push origin feature/your-new-feature

7. Open a Pull Request (PR):
   • Go to the original GDSC-FSC/gdsc-farmingdale-links repository on GitHub.
   • You should see a prompt to create a new pull request from your recently pushed branch.
   • Provide a clear title and detailed description of your changes, referencing any relevant issues.

• main branch: This branch represents the latest stable, production-ready code. Do not commit directly to main.
• develop branch: New features and bug fixes should generally be merged into develop first, then develop is merged into main for releases.
• Feature Branches: Create branches prefixed with feature/ for new features (e.g., feature/add-dark-mode).
• Bugfix Branches: Create branches prefixed with bugfix/ for bug fixes (e.g., bugfix/fix-event-date-display).
• Pull Request Reviews: All PRs require at least one approval from a maintainer before merging. Address any feedback promptly.

• Biome: We use Biome for code formatting and linting. Ensure your code adheres to the project's Biome configuration (biome.json).
  • Run npm run format:fix and npm run lint:fix before committing.
• TypeScript: All new code should be written in TypeScript, ensuring type safety and improving code maintainability.
• ESLint/Prettier: Though Biome is primary, ensure you don't introduce conflicts if other tools like Prettier (.prettierrc) are also configured for specific file types.
• Meaningful Names: Use descriptive names for variables, functions, and components.
• Modularity: Keep components small, focused, and reusable.

• Unit Tests: Write unit tests using Vitest for critical functions and components. Place them alongside the code they test (e.g., component.test.ts).
• End-to-End (E2E) Tests: For major user flows, contribute to or create E2E tests using Vitest (refer to vitest.e2e.config.ts).
• Test Coverage: Aim for reasonable test coverage, especially for core logic and critical UI interactions.

To ensure a smooth development environment:

• VS Code Extensions:
  • Biome (for integrated formatting and linting)
  • Tailwind CSS IntelliSense
  • ESLint (if not fully replaced by Biome)
  • Prettier (if still used alongside Biome)
• Editor Configuration: Ensure your editor is configured to use Biome for .ts, .tsx, .js, .jsx, and .json files.
• Pre-commit Hooks: Consider using husky (if configured in package.json) to automatically run linting and formatting before commits.

⬆️ Back to Top

Essential information about the project's legal standing and key contributors.

This project is licensed under the MIT License. You are free to use, modify, and distribute this software, provided you include the original copyright and license notice.

See the LICENSE file for full details.

We extend our sincere gratitude to the following projects and individuals for their contributions and inspiration:

• Google Developer Student Clubs (GDSC): For fostering a vibrant community and providing the platform for this project.
• React: The foundational library for our user interface.
• Vite: Our blazing-fast build tool.
• TypeScript: For type safety and improved developer experience.
• Firebase: For authentication and hosting.
• Shadcn UI & NextUI: For providing beautiful and accessible UI components.
• Tailwind CSS: For an efficient and powerful styling framework.
• Framer Motion: For enhancing user interaction with fluid animations.
• Biome: For maintaining code quality and consistency.
• Vitest: For a fast and modern testing framework.
• All Contributors: To everyone who has contributed code, reported bugs, or provided feedback – thank you!

For any inquiries, collaborations, or support, please reach out to the GDSC Farmingdale leadership team or the maintainers of this repository:

• GitHub Repository: GDSC-FSC/gdsc-farmingdale-links
• GDSC Farmingdale Website: (Placeholder, usually linked from the app)
• Maintainer Contact: You can open an issue on the GitHub repository, or for direct communication, refer to the GDSC Farmingdale contact information provided on their official channels.

⬆️ Back to Top

Additional resources and helpful information.

// Example: Event Data Structure
interface Event {
    id: string;
    title: string;
    description: string;
    date: string; // ISO 8601 format
    time: string;
    location: string;
    registrationLink?: string;
    media: {
        images?: string[]; // URLs to event images
        videos?: string[]; // URLs to event videos (e.g., YouTube embeds)
    };
    tags?: string[];
    isUpcoming: boolean;
}

// Example: Link Data Structure
interface LinkItem {
    id: string;
    title: string;
    url: string;
    icon?: string; // Icon identifier or URL
    category?: string;
}

// Example: Contact Form Submission
interface ContactFormPayload {
    name: string;
    email: string;
    subject: string;
    message: string;
}

⬆️ Back to Top