RamHacks '25 Website Documentation

---

🚀 The official platform for Farmingdale State Hacks RamHacks '25, built with cutting-edge web technologies to deliver an exceptional event experience.

---

🧭 Table of Contents

• 1. Overview & Introduction
• 2. Feature Highlights
• 3. Architecture & Technology Stack
  • 3.1. High-Level Component Diagram
  • 3.2. Architectural Components
  • 3.3. Core Technology Stack
• 4. Getting Started
  • 4.1. Prerequisites
  • 4.2. Installation & Setup
  • 4.3. Configuration
  • 4.4. Running the Application
• 5. Usage & Workflows
  • 5.1. Common Development Commands
  • 5.2. Database Management
  • 5.3. UI Component Management
• 6. Limitations, Known Issues & Future Roadmap
  • 6.1. Current Limitations
  • 6.2. Known Issues
  • 6.3. Future Roadmap
• 7. Contributing & Development Guidelines
  • 7.1. How to Contribute
  • 7.2. Branching & Pull Request Guidelines
  • 7.3. Code Style & Quality
  • 7.4. Testing Strategy
  • 7.5. Development Environment Setup
• 8. License, Credits & Contact
  • 8.1. License
  • 8.2. Acknowledgments & Dependencies
  • 8.3. Maintainers & Contact
• 9. Appendix
  • 9.1. Changelog
  • 9.2. Frequently Asked Questions (FAQ)
  • 9.3. Troubleshooting Guide
  • 9.4. API Reference

---

1. Overview & Introduction

The RamHacks '25 Website is the official online platform for the RamHacks 2025 hackathon, organized by Farmingdale State Hacks. This project serves as the central hub for all event-related information, aiming to provide a seamless and engaging experience for participants, sponsors, and organizers.

Purpose & Goals:

• Inform: Provide comprehensive details about RamHacks '25, including FAQs, sponsors, and featured clubs.
• Engage: Create an inviting and accessible online presence that encourages participation and excitement for the event.
• Support: Streamline event logistics by acting as a central point of reference for all stakeholders.
• Showcase: Highlight the innovative spirit of Farmingdale State College's hacking community.

Why it Matters / Problem it Solves: In today's fast-paced digital world, a well-structured and user-friendly website is crucial for the success of any major event. This application solves the challenge of consolidating diverse information into an easily navigable and aesthetically pleasing platform, ensuring that potential attendees and partners can quickly find what they need, understand the value proposition of RamHacks, and prepare for an enriching experience. It prevents information fragmentation and provides a single source of truth for the event.

Target Audience:

• Prospective Hackathon Participants: Students from Farmingdale State College and beyond interested in joining the hackathon.
• Current Participants: Attendees looking for the latest announcements and resources during the event.
• Sponsors & Partners: Organizations seeking information about sponsorship opportunities and event impact.
• Farmingdale State College Community: Faculty, staff, and students interested in the hackathon's activities.
• Event Organizers & Volunteers: For managing and disseminating information efficiently.

⬆️ Back to Top

---

2. Feature Highlights

The RamHacks '25 website is designed with a focus on delivering a modern, responsive, and informative experience.

Key Features:

• ✅ Dynamic Event Information:
  • Comprehensive About section detailing the hackathon's mission and history.
  • Detailed FAQ section to address common queries efficiently.
  • Dedicated Sponsors page to acknowledge and showcase our valuable partners.
  • Clubs showcase to highlight participating student organizations.
• 🎨 Modern & Responsive User Interface:
  • Built with Tailwind CSS v4 for highly customizable and efficient styling.
  • Utilizes shadcn/ui components for a consistent, accessible, and beautiful UI experience.
  • Fully responsive design ensures optimal viewing across all devices (desktops, tablets, mobiles).
  • 💡 Includes a Theme Toggle (lib/components/theme-toggle.tsx) for seamless light/dark mode switching.
• ⚙️ Robust & Scalable Architecture:
  • Powered by TanStack Start, React 19 (with React Compiler), and TanStack Router for a high-performance, maintainable frontend.
  • TanStack Query for efficient and reliable server-state management.
  • Drizzle ORM with PostgreSQL for type-safe and performant database interactions.
  • Containerized with Docker for consistent development and production environments.
• 🧪 Comprehensive Testing & Quality Assurance:
  • Extensive End-to-End (E2E) testing using Cypress and Playwright to ensure critical user flows are bug-free.
  • Integrated ESLint and Prettier for consistent code style and quality across the codebase.
  • GitHub Actions for automated CI/CD, running tests and deployments on every push.
• 🔒 Security & Reliability:
  • Sentry integration for real-time error monitoring and performance tracing in production.
  • XSS Protection utilities (lib/utils/xss.ts) to mitigate cross-site scripting vulnerabilities.
  • Environment variable management via .env for secure configuration.

⬆️ Back to Top

---

3. Architecture & Technology Stack

The RamHacks '25 website employs a modern, full-stack architecture designed for performance, scalability, and developer experience. It leverages the power of server-side rendering (SSR) and client-side interactivity provided by TanStack Start, backed by a robust PostgreSQL database.

3.1. High-Level Component Diagram

This diagram illustrates the primary components and their interactions within the application ecosystem.

graph TD
    A[Client Browser] -->|Requests UI/Data| B(TanStack Start Frontend)
    B -->|API Requests| C(TanStack Start Backend API)
    C -->|ORM Interactions| D(Drizzle ORM)
    D -->|SQL Queries| E[PostgreSQL Database]

    subgraph Development/Deployment
        F[Developer] -->|Code/Push| G(GitHub)
        G -->|CI/CD Trigger| H(GitHub Actions)
        H -->|Build/Test/Deploy| I(Docker)
        I --> J(Production Server)
    end

    B --- K(Sentry Monitoring)
    C --- K
    J --- K

    style A fill:#DCEFFB,stroke:#3498DB,stroke-width:2px,color:#333;
    style B fill:#E6FFE6,stroke:#2ECC71,stroke-width:2px,color:#333;
    style C fill:#FFE6E6,stroke:#E74C3C,stroke-width:2px,color:#333;
    style D fill:#F5ECFF,stroke:#9B59B6,stroke-width:2px,color:#333;
    style E fill:#D0E6F0,stroke:#3498DB,stroke-width:2px,color:#333;
    style K fill:#F9DCEB,stroke:#E91E63,stroke-width:2px,color:#333;
    style G fill:#E8E8E8,stroke:#666,stroke-width:1px,color:#333;
    style H fill:#E0E0FF,stroke:#6A5ACD,stroke-width:1px,color:#333;
    style I fill:#DCF0E6,stroke:#27AE60,stroke-width:1px,color:#333;
    style J fill:#FFEDCC,stroke:#F39C12,stroke-width:1px,color:#333;

Loading

3.2. Architectural Components

1. Client Browser (A): The user's web browser, which interacts with the deployed application.
2. TanStack Start Frontend (B):
   • The primary user interface, built with React 19 and TanStack Router.
   • Responsible for rendering UI components, handling user input, and making API requests.
   • Leverages TanStack Query for efficient data fetching and caching on both client and server.
   • Uses Tailwind CSS v4 and shadcn/ui for styling and UI components.
3. TanStack Start Backend API (C):
   • The server-side component of the TanStack Start application, handling API routes (e.g., app/routes/api/health).
   • Processes incoming requests, interacts with the database via Drizzle ORM, and serves data to the frontend.
   • Handles server-side rendering (SSR) for initial page loads, improving performance and SEO.
4. Drizzle ORM (D):
   • A TypeScript ORM used to interact with the PostgreSQL database.
   • Provides type-safe database queries and schema migrations (drizzle.config.ts, .drizzle/).
   • Decouples the application logic from raw SQL, enhancing maintainability.
5. PostgreSQL Database (E):
   • The persistent data store for the application, managed locally via docker-compose.yml.
   • Stores all event-related data, such as FAQs, sponsor information, and potentially user/registration data.
6. Sentry Monitoring (K):
   • Integrated error tracking and performance monitoring platform.
   • Captures and reports errors from both client-side (frontend) and server-side (backend) components, providing real-time insights into application health.
7. GitHub Actions (H):
   • Automated CI/CD workflows (.github/workflows/).
   • Runs tests, builds the application, and deploys it upon code changes, ensuring continuous quality and delivery.
8. Docker (I):
   • Containerization technology used for packaging the application and its dependencies into a consistent, portable unit (Dockerfile, docker-compose.yml).
   • Facilitates easy local development setup (e.g., database service) and consistent deployment environments.

3.3. Core Technology Stack

Category	Technology	Description
Framework	TanStack Start	A full-stack React framework for building performant, type-safe web applications.
Frontend Library	React 19	JavaScript library for building user interfaces, leveraging the new React Compiler.
Routing	TanStack Router	Type-safe, file-based routing for React applications, integrated with TanStack Start.
Data Fetching	TanStack Query	Powerful asynchronous state management library for React, enabling efficient data fetching and caching.
Styling	Tailwind CSS v4	A utility-first CSS framework for rapidly building custom designs.
UI Components	shadcn/ui	Reusable UI components built with Radix UI and Tailwind CSS, offering high customizability.
Database ORM	Drizzle ORM	TypeScript ORM for SQL databases, providing type safety and powerful schema migrations.
Database	PostgreSQL	A powerful, open-source relational database system.
Containerization	Docker	Platform for developing, shipping, and running applications in containers.
Package Manager	Bun	A fast, all-in-one JavaScript runtime, bundler, transpiler, and package manager.
Testing (E2E)	Cypress & Playwright	Robust end-to-end testing frameworks for modern web applications.
Error Monitoring	Sentry	Real-time error tracking, performance monitoring, and crash reporting.
CI/CD	GitHub Actions	Automation platform for building, testing, and deploying code directly from GitHub.

⬆️ Back to Top

---

4. Getting Started

Follow these steps to set up and run the RamHacks '25 website on your local machine.

4.1. Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: The project requires a recent version of Node.js.
  • 🔍 Check version: node -v
  • The project recommends the latest stable version (e.g., node:22-bullseye-slim in Dockerfile). It's best to use nvm install if you have .nvmrc support, or install Node.js v20+.
• Bun: The preferred package manager and JavaScript runtime for this project.
  • 🔍 Check version: bun -v
  • Installation: curl -fsSL https://bun.sh/install | bash
• Docker & Docker Compose: Essential for running the PostgreSQL database locally.
  • 🔍 Check versions: docker -v, docker compose -v
  • Installation: Get Docker

4.2. Installation & Setup

Click to expand Installation Steps

1. Clone the repository:

   git clone https://github.com/Farmingdale-State-Hacks/ramhacks-25-s.git
   cd ramhacks-25-s

2. Install dependencies: This project uses bun as its package manager.

   bun install

   ✅ Success Note: This might take a few moments. bun will install all required Node.js packages.

3. Set up environment variables: Copy the example environment file and update it with your local configurations.

   cp .env.example .env

   Then, open .env in your editor and fill in the necessary values. ⚠️ Important: At a minimum, you'll need to set DATABASE_URL and potentially SENTRY_DSN if you want local Sentry integration. For local development, the DATABASE_URL can point to your local Dockerized PostgreSQL instance.

   # .env example (fill these values)
   NODE_ENV=development
   VITE_BASE_URL=http://localhost:3000
   DATABASE_URL="postgresql://user:password@localhost:5432/ramhacks_db"
   # Example Sentry Config (optional for local dev)
   SENTRY_DSN=""
   SENTRY_AUTH_TOKEN=""
   SENTRY_ORG=""
   SENTRY_PROJECT=""
   SENTRY_ENVIRONMENT=development

4. Start the local PostgreSQL database: We use docker-compose to spin up a PostgreSQL instance.

   docker compose up -d db

   This command starts the db service defined in docker-compose.yml in detached mode. 💡 Tip: To verify the database is running, you can use docker compose logs db or docker ps. The db service runs on port 5432.

5. Run Drizzle migrations: After setting your DATABASE_URL in .env and starting the database, push the database schema using Drizzle Kit. This creates the tables defined in your schema.

   bun run db:push

   If you're starting fresh, you can also consider bun run db:generate to create new migration files, but db:push applies the current schema directly. 🔍 Verification: You can connect to your local PostgreSQL instance (e.g., using psql, DBeaver, or another SQL client) with the credentials from your docker-compose.yml and .env to confirm tables are created.

4.3. Configuration

The application's configuration is managed through a combination of files:

• .env: For environment-specific variables (database credentials, API keys, Sentry DSN, etc.). This file is not committed to version control.
• config/config.ts: For application-wide, non-sensitive configurations that are part of the codebase.
• app.config.ts: TanStack Start's specific configuration, including Vite plugins, React Compiler, Sentry setup, and PWA options.
• drizzle.config.ts: Drizzle ORM configuration for database migrations and schema management.

Important Environment Variables:

• NODE_ENV: Set to development for local development, production for deployments.
• VITE_BASE_URL: The base URL for the frontend. Default: http://localhost:3000.
• DATABASE_URL: Connection string for your PostgreSQL database (e.g., postgresql://user:password@host:port/database).
• SENTRY_DSN, SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT: Sentry configuration for error monitoring. These are crucial for production environments.

4.4. Running the Application

Click to expand Running Instructions

Development Mode

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

bun run dev

This will typically start the application on http://localhost:3000. Open your browser to this address to see the website. Any code changes will automatically trigger a rebuild and refresh.

Production Build & Run

To create an optimized production build and then run it:

1. Build the application:

   bun run build

   This command compiles the frontend and backend code, optimizing it for production. The output will be in a dist directory.

2. Start the production server:

   bun run start

   This command serves the optimized build. This is how the application would typically run in a production environment (e.g., on Vercel, a custom server, or within a Docker container).

Running with Docker

For a fully containerized environment, you can build and run the application using Docker.

1. Build the Docker image:

   docker build -t ramhacks-25-s .

   This command builds the Docker image based on the Dockerfile.

2. Run the Docker container:

   docker run -p 3000:3000 -d --name ramhacks-app ramhacks-25-s

   This command starts a container from your built image, mapping port 3000 from the container to port 3000 on your host, and runs it in detached mode.

3. Access the application: Open your browser to http://localhost:3000.

⬆️ Back to Top

---

5. Usage & Workflows

This section outlines common commands and workflows for developing and managing the RamHacks '25 website.

5.1. Common Development Commands

The package.json defines several useful scripts to streamline development:

• bun run dev:

  bun run dev

  Starts the development server with hot-reloading. Essential for active development.

• bun run build:

  bun run build

  Creates a production-ready build of the application. This generates optimized static assets and server-side code.

• bun run start:

  bun run start

  Serves the production build. Use this after bun run build to run the application in a production-like environment.

• bun run test:

  bun run test

  Runs all tests (Playwright and Cypress). This command acts as a wrapper for the different testing suites. See also: Testing Strategy

• bun run test:e2e:

  bun run test:e2e

  Specifically runs the Playwright end-to-end tests.

• bun run test:e2e:ui:

  bun run test:e2e:ui

  Opens the Playwright UI for interactive test debugging.

• bun run cypress:open:

  bun run cypress:open

  Opens the Cypress Test Runner UI, allowing you to select and run individual Cypress tests or suites.

• bun run cypress:run:

  bun run cypress:run

  Runs all Cypress tests headlessly in the command line (useful for CI/CD).

• bun run format:

  bun run format

  Formats all code files using Prettier according to the .prettierrc configuration. This helps maintain consistent code style.

• bun run lint:

  bun run lint

  Runs ESLint to analyze the code for potential errors and style violations.

5.2. Database Management

The project uses Drizzle ORM for database interactions and migrations.

• bun run db:push:

  bun run db:push

  Pushes the current schema defined in lib/server/schema/index.ts to the connected database. This is useful for quickly synchronizing the schema during local development. ⚠️ Warning: Be cautious using db:push in production, as it can be destructive if not used correctly. It's generally preferred to use explicit migrations (db:migrate) for production environments.

• bun run db:generate:

  bun run db:generate --name your-migration-name

  Generates a new Drizzle migration file based on the differences between your schema and the current database state. The --name flag is important for descriptive migration names. These files are typically stored in the .drizzle directory.

• bun run db:migrate:

  bun run db:migrate

  Applies all pending migration files from the .drizzle directory to the database. This is the recommended way to manage schema changes in production.

5.3. UI Component Management

The project leverages shadcn/ui for its UI components. These components are automatically configured via components.json.

• Adding a new shadcn/ui component:

  bun run ui:add button # Example: adds the Button component

  This command uses the npx shadcn-ui@latest add utility to download and configure a specified component into your lib/components/ui directory, following the settings in components.json.

⬆️ Back to Top

---

6. Limitations, Known Issues & Future Roadmap

This section outlines the current state of the application, any known shortcomings, and plans for future enhancements.

6.1. Current Limitations

• Initial Feature Set: As of the current version, the website primarily focuses on static event information. Dynamic features like user registration, team formation, or project submission are not yet implemented.
• Authentication/Authorization: While Better Auth is mentioned in the initial README, a fully integrated authentication system for users (e.g., participants, judges, mentors) is not actively deployed or fully utilized for website content access control at this stage.
• Real-time Updates: Event announcements currently require a full page refresh or re-deployment. There's no real-time push notification system.

6.2. Known Issues

• None currently documented: While comprehensive testing is in place, minor edge cases or browser-specific rendering issues might exist but are not yet formally tracked. Please report any issues you encounter via the GitHub Issue Tracker.

6.3. Future Roadmap

The RamHacks '25 website is continuously evolving. Here are some planned enhancements and potential feature requests:

• Participant Registration System:
  • Secure user registration and login.
  • Profile management for participants.
  • Team creation and management functionalities.
• Project Submission & Showcase:
  • Platform for hackers to submit their projects.
  • Gallery to showcase submitted projects during and after the hackathon.
• Mentor & Volunteer Management:
  • Features for mentors and volunteers to sign up and manage their availability.
  • Matching system for participants to connect with mentors.
• Live Announcements & Notifications:
  • Integration of a real-time system (e.g., WebSockets) for instant event announcements.
• Sponsor Portal:
  • Enhanced features for sponsors, including customizable profiles and analytics.
• Improved Accessibility:
  • Conducting in-depth accessibility audits and implementing further improvements beyond current shadcn/ui foundations.
• Performance Optimizations:
  • Further fine-tuning performance, potentially exploring advanced caching strategies or serverless functions for specific workloads.

💡 Feature Requests: Have an idea for a new feature? Please open a feature request issue on GitHub!

⬆️ Back to Top

---

7. Contributing & Development Guidelines

We welcome contributions from the community to make RamHacks '25 even better! Please follow these guidelines to ensure a smooth and collaborative development process.

7.1. How to Contribute

1. Fork the Repository: Start by forking the ramhacks-25-s repository to your GitHub account.
2. Clone Your Fork: Clone your forked repository to your local machine:

   git clone https://github.com/YOUR_USERNAME/ramhacks-25-s.git
   cd ramhacks-25-s

3. Create a New Branch: Always create a new branch for your feature or bug fix:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b bugfix/your-bug-fix-name

4. Make Your Changes: Implement your feature or fix the bug.
5. Test Your Changes: Ensure your changes work as expected and don't introduce regressions. Run relevant tests (see Testing Strategy).
6. Commit Your Changes: Write clear, concise commit messages following the Conventional Commits specification (e.g., feat: add new feature, fix: correct typo in FAQ). The project uses git-conventional-commits.yaml for validation.
7. Push to Your Fork:

   git push origin feature/your-feature-name

8. Open a Pull Request (PR):
   • Go to the original ramhacks-25-s repository on GitHub.
   • You should see a prompt to open a PR from your recently pushed branch.
   • Fill out the PR template thoroughly, describing your changes, their purpose, and any relevant details.
   • Link to any related issues.

7.2. Branching & Pull Request Guidelines

• Main Branch: The main branch is always considered stable and deployable. All new features and bug fixes should be developed in separate branches.
• Branch Naming:
  • feature/descriptive-name: For new features.
  • bugfix/descriptive-name: For bug fixes.
  • chore/descriptive-name: For maintenance tasks, build process changes, etc.
  • docs/descriptive-name: For documentation updates.
• Pull Request Reviews: All PRs require at least one approval from a maintainer before merging. Address any feedback provided during the review process.
• CI/CD Checks: Ensure all GitHub Actions (tests, linting, build) pass successfully on your PR before requesting a review.

7.3. Code Style & Quality

• ESLint: We use ESLint for static code analysis to catch common errors and enforce coding standards.
  • Run bun run lint before committing to identify and fix issues.
• Prettier: Code formatting is handled by Prettier to ensure consistent style across the entire codebase.
  • Run bun run format before committing. Your IDE might also integrate Prettier on save.
• TypeScript: All new code should be written in TypeScript, leveraging its type-safety benefits.
• Component Structure: Follow the existing component structure within lib/components and app/routes. Keep components small, focused, and reusable.

7.4. Testing Strategy

The project has a robust testing suite to ensure high quality and prevent regressions.

• End-to-End (E2E) Testing:
  • Playwright: Used for broad E2E test coverage, located in the e2e/ directory.
    • Run bun run test:e2e for headless execution.
    • Run bun run test:e2e:ui for interactive UI mode.
  • Cypress: Also used for E2E testing, particularly for specific user flows and component interactions, located in the cypress/ directory.
    • Run bun run cypress:run for headless execution.
    • Run bun run cypress:open to launch the Cypress Test Runner.
• Unit/Integration Testing: While not explicitly detailed in package.json scripts, individual components and utility functions should ideally have dedicated unit tests (e.g., using @testing-library/react with a test runner like Vitest or Jest). You can find examples in TESTING.md (if it exists and is detailed).

💡 Important: Always run bun run test (or specific test suites) before submitting a Pull Request to ensure your changes haven't broken existing functionality.

7.5. Development Environment Setup

• Docker Compose for Database: The docker-compose.yml provides a quick way to set up a local PostgreSQL instance. Always ensure it's running (docker compose up -d db) before starting the dev server or running migrations.
• IDE Configuration: Ensure your IDE (e.g., VS Code) has ESLint, Prettier, and TypeScript extensions installed and configured to use the project's settings. .editorconfig helps ensure consistent indentation and line endings.
• Node Version Manager (NVM): If you manage multiple Node.js versions, use nvm install and nvm use in the project directory based on the .nvmrc file to ensure you're using the correct Node.js version.

⬆️ Back to Top

---

8. License, Credits & Contact

8.1. License

This project is licensed under the MIT License. See the LICENSE file in the root of the repository for full details.

MIT License

Copyright (c) 2024 Farmingdale State Hacks

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

8.2. Acknowledgments & Dependencies

We extend our gratitude to the following projects and their communities for providing the foundational technologies and tools that make the RamHacks '25 website possible:

• Farmingdale State Hacks: The organizing body behind RamHacks.
• TanStack Start: The excellent full-stack framework for React.
• React: The core UI library.
• Tailwind CSS: For efficient and highly customizable styling.
• shadcn/ui: For beautiful and accessible UI components.
• Drizzle ORM & PostgreSQL: For robust and type-safe data management.
• Docker & Bun: For modern development and deployment workflows.
• Cypress & Playwright: For comprehensive testing.
• Sentry: For critical error monitoring.
• All other open-source dependencies listed in package.json.

Your contributions to the open-source ecosystem are invaluable!

8.3. Maintainers & Contact

This project is actively maintained by the Farmingdale State Hacks development team.

• GitHub Repository: https://github.com/Farmingdale-State-Hacks/ramhacks-25-s
• General Inquiries: (Placeholder for official email, e.g., info@ramhacks.io)
• Development Issues: Please use the GitHub Issue Tracker for bug reports and feature requests.

⬆️ Back to Top

---

9. Appendix

9.1. Changelog

Click to expand recent updates

v1.0.0 (YYYY-MM-DD)

• Initial stable release of the RamHacks '25 website.
• Core information pages (About, FAQ, Sponsors, Clubs).
• Full TanStack Start, React 19, Tailwind CSS v4, shadcn/ui integration.
• Drizzle ORM with PostgreSQL database backend.
• Docker containerization for local development and deployment.
• Comprehensive E2E testing with Cypress and Playwright.
• CI/CD pipelines with GitHub Actions.
• Sentry error monitoring integration.

9.2. Frequently Asked Questions (FAQ)

Click to expand common questions

Q: What is RamHacks? A: RamHacks is Farmingdale State College's annual student-run hackathon, bringing together students from various disciplines to build innovative projects, learn new skills, and connect with peers and mentors.

Q: How can I register for RamHacks? A: Registration details, including links and deadlines, will be announced soon on the website's homepage and dedicated sections. Please keep an eye on updates!

Q: I found a bug or have a feature idea. How can I contribute? A: We welcome all contributions! Please refer to our Contributing Guidelines for instructions on how to submit bug reports, feature requests, or code contributions via GitHub Pull Requests.

Q: What technologies are used to build this website? A: This website is built using a modern stack including TanStack Start, React 19, Tailwind CSS v4, shadcn/ui, Drizzle ORM, PostgreSQL, and Docker. You can find a complete list in the Technology Stack section.

9.3. Troubleshooting Guide

Click to expand common troubleshooting steps

• "bun: command not found":
  • Solution: Ensure Bun is properly installed and its executable path is included in your system's PATH environment variable. Refer to Bun's official installation guide.
• Database Connection Issues (DATABASE_URL errors):
  • Check .env: Verify that DATABASE_URL is correctly set in your .env file and matches the credentials in docker-compose.yml.
  • Docker Container Status: Ensure your PostgreSQL container is running: docker ps. If not, start it with docker compose up -d db.
  • Port Conflicts: Make sure no other application is using port 5432 on your machine.
  • Firewall: Check if your firewall is blocking connections to localhost:5432.
• "Error: bun install failed" / Dependency Issues:
  • Clean Cache: Try clearing Bun's cache: bun cache clean.
  • Node.js Version: Ensure you are using the recommended Node.js version specified in .nvmrc (nvm use).
  • Delete node_modules: Remove the node_modules directory and bun.lockb, then run bun install again.
• UI Not Updating / Hot Reloading Issues:
  • Restart Dev Server: Sometimes, simply restarting bun run dev can resolve these issues, especially after significant dependency changes.
  • Check Browser Console: Look for errors in your browser's developer console.
• Cypress/Playwright Tests Not Running:
  • Ensure Dev Server is Running: E2E tests require the application to be running first (bun run dev).
  • Browser Launch Issues: For Cypress/Playwright UI, check if the required browser binaries are installed and accessible.
  • Console Output: Review the console output from the test runner for specific error messages.

9.4. API Reference

The RamHacks '25 website leverages a minimal set of API routes, primarily for health checks and potential future dynamic content.

• Health Check Endpoint:
  • URL: /api/health
  • Method: GET
  • Description: A simple endpoint to check the operational status of the backend API. Returns a success message and server timestamp.
  • Example Response (200 OK):

    {
      "status": "ok",
      "message": "API is healthy",
      "timestamp": "2024-07-20T12:00:00.000Z"
    }

Further API endpoints will be documented here as they are developed for features like registration, project submission, etc. For now, most data is fetched directly via TanStack Query's server-side functions.

⬆️ Back to Top