Eventra

Modern event and hackathon platform for communities, organizers, and contributors.

---

Project Status Notice

🚧 Eventra is actively maintained and welcomes contributions from the open-source community. Please check existing issues before creating new ones and follow the contribution guidelines when submitting pull requests.

Table of Contents

• Project Status Notice
• Overview
• Key Features
• Tech Stack
• Project Architecture
• Project Structure
• Prerequisites
• Local Development
• Docker Development
• Environment Variables
• Available Scripts
• Testing and Quality
• SSE Mock Server (Optional)
• Deployment
• Documentation
• Contributing
• License
• Contributors
• Maintainers
• Mentor
• Star History

---

Overview

Eventra is an open-source frontend application built with React and Vite. It supports event discovery, registration, dashboards, hackathons, collaboration features, feedback flows, and role-based access experiences.

This repository contains the frontend application. The Spring Boot backend is maintained in a separate repository — all API traffic is proxied to it both in production (via Vercel rewrites) and in local development (via Vite proxy).

• Frontend repo: https://github.com/SandeepVashishtha/Eventra
• Backend repo: https://github.com/SandeepVashishtha/Eventra-Backend
• Backend API base: https://eventra-backend-springboot-eybhdvaubxcua7ha.centralindia-01.azurewebsites.net
• Swagger: https://eventra-backend-springboot-eybhdvaubxcua7ha.centralindia-01.azurewebsites.net/swagger-ui/index.html

Key Features

• Event and hackathon discovery, filtering, and registration flows
• Auth-aware routes with protected pages and role-aware behavior
• Dashboard and profile surfaces for users and organizers
• Real-time and offline-friendly UX utilities
• Feedback, recommendation, and community engagement modules
• Extensive utility and behavior test coverage

Tech Stack

• React 18.2
• React Router 7
• Vite 8
• Tailwind CSS 4
• Framer Motion
• Lucide React
• Playwright (E2E)
• ESLint and Prettier

Project Architecture

Below is the high-level architecture of Eventra:

graph TD
    Client[Client: React/Vite] --> Assets[Assets: public/]
    Client --> State[State: Context/Hooks]
    Client --> Backend[Backend: Spring Boot API]
    Backend --> Azure[Azure Spring Boot]
    Client -.-> VercelRewrite[Vercel /api/* Rewrite]
    VercelRewrite --> Backend

Loading

Project Structure

Eventra/
|-- docs/                # Architecture, env setup, onboarding, security docs
|-- public/              # Static assets
|-- scripts/             # Validation and automation scripts
|-- src/
|   |-- Pages/           # Route-level pages
|   |-- components/      # Shared and feature components
|   |-- context/         # React context providers
|   |-- hooks/           # Custom hooks
|   |-- utils/           # Utility modules
|   |-- config/          # Runtime/env config helpers
|   |-- App.jsx
|   `-- index.jsx
|-- tests/               # Node-based unit/integration tests
|-- vite.config.js
|-- vercel.json
`-- README.md

Prerequisites

• Node.js >=22.x
• npm >=9.6.4

Local Development

1. Clone and install:

git clone https://github.com/SandeepVashishtha/Eventra.git
cd Eventra
npm install

1. Create your env file:

cp .env.example .env

Tip: If your operating system does not support cp, copy the file manually or use copy .env.example .env on Windows.

1. Start dev server:

npm run dev

App runs at http://localhost:3000 (configured in vite.config.js).

Docker Development

You can run Eventra fully containerized using Docker Compose to ensure a consistent environment:

1. Clone the repository and setup your environment variables:

git clone https://github.com/SandeepVashishtha/Eventra.git
cd Eventra
cp .env.example .env

1. Start the local development container:

docker compose up eventra-dev

The app will be available at http://localhost:3000 with hot-reloading enabled.

1. Build and test the production container locally:

docker compose up --build eventra-prod

The production-optimized build will be served via Nginx at http://localhost:8080.

Environment Variables

Use .env.example as the source of truth. See docs/ENV_SETUP_GUIDE.md for detailed configuration information.

Variable	Required	Purpose
BACKEND_URL	No	Backend origin (highest priority, overrides others)
VITE_API_URL	No	Backend API base URL (Vite - preferred)
REACT_APP_API_URL	No	Backend API base URL (CRA compatibility)
REACT_APP_GITHUB_REPO	No	Public repo identifier used in metadata
REACT_APP_PUBLIC_URL	No	Canonical public app URL
REACT_APP_VAPID_PUBLIC_KEY	No	Public web-push key
REACT_APP_CSP_REPORT_URI	No	CSP report endpoint
REACT_APP_SENTRY_DSN	No	Sentry browser error reporting DSN, used only in production
JWT_SECRET	Yes (server-side)	JWT signing secret for Edge Middleware auth verification
DATABASE_URL	Yes (server-side, production)	Database connection URL for persistent authentication storage
KV_REST_API_URL	Yes (server-side, production)	Vercel KV/Redis REST API URL for distributed rate limiting
KV_REST_API_TOKEN	Yes (server-side, production)	Vercel KV/Redis REST API token for distributed rate limiting
BLOCKED_COUNTRIES	No (server-side)	Comma-separated ISO 3166-1 alpha-2 country codes to block

Examples:

VITE_API_URL=https://api.example.com

or:

BACKEND_URL=https://api.example.com

Backend Configuration: All backend endpoint configuration is centralized in src/config/backendConfig.js. The system resolves backend URLs in priority order: BACKEND_URL → VITE_API_URL → REACT_APP_API_URL. In development, defaults to http://localhost:8080. In production, no automatic fallback - configuration must be explicitly set to avoid configuration drift.

Security note: never place private secrets in REACT_APP_* or VITE_* variables because they are exposed to the client bundle.

Geographic Access Restrictions

The Edge Middleware supports configurable country-based access restrictions via the BLOCKED_COUNTRIES environment variable. This is a server-side configuration that affects all incoming requests.

Configuration:

• Set BLOCKED_COUNTRIES to a comma-separated list of two-letter ISO 3166-1 alpha-2 country codes
• Leave empty to allow access from all countries (default behavior)
• Country codes are case-insensitive and whitespace is trimmed automatically

Examples:

# Block specific countries
BLOCKED_COUNTRIES=CU,IR,KP,SY,RU

# Allow all countries (default)
BLOCKED_COUNTRIES=

Behavior:

• Requests from blocked countries receive HTTP 451 (Unavailable For Legal Reasons)
• Blocked requests are logged with the country code for monitoring
• Self-hosted deployments can configure this based on their requirements
• No restrictions are applied when the variable is empty or unset

Available Scripts

Command	Description
npm run dev	Start local dev server
npm run start	Alias to Vite dev server
npm run build	Production build
npm run preview	Preview production build locally
npm run lint	Run ESLint on src/
npm run lint:fix	Auto-fix lint issues
npm run format	Run Prettier on source files
npm run test	Run unit test suite
npm run test:e2e	Run Playwright E2E tests
npm run check	Run lint + tests together (CI validation)
npm run storybook	Start Storybook
npm run build-storybook	Build Storybook static output

Testing and Quality

npm run lint
npm run test
npm run test:e2e

SSE Mock Server (Optional)

For local realtime testing:

node sse-mock-server.js

Required environment variables:

• JWT_SECRET - JWT signing secret for token generation and validation. Generate with: openssl rand -base64 32

Optional environment flags:

• SSE_MOCK_PORT (default 8080)
• ALLOWED_ORIGIN (default http://localhost:3000)
• SSE_DEBUG (true or false)

Deployment

Vercel configuration is checked in via vercel.json:

• Build command: npm run lint && GENERATE_SOURCEMAP=false npm run build
• Output directory: build
• /api/* is rewritten to the hosted Spring Boot backend (the sole API provider)
• No serverless functions are deployed — the api/ directory was removed as dead code

Documentation

• Architecture and Roles
• Environment Setup Guide
• Frontend Onboarding
• Security Migration Notes
• API Documentation Notes

Contributing

• Follow CODE_OF_CONDUCT.md
• Open focused pull requests with clear scope and test notes
• Issues may be auto-unassigned after inactivity by workflow: auto-unassign-stale-issues.yml

License

Licensed under Apache 2.0. See LICENSE.

Contributors

Maintainers

Sandeep Vashishtha

Rhythm

Mentor

Guidance and mentorship for the Eventra project are provided by the project leadership team. Contributors are encouraged to use GitHub Issues and Discussions for questions, suggestions, and collaboration.

Star History

Built by the Eventra community.

---