Summerfest-admin-fe - Documentation

🔎 Background

Overview

summerfest-admin-fe is the frontend admin panel for Summerfest RISTEK. The service is used by internal admins to authenticate, review applicant submissions, filter and search records, verify Datathon submissions, delete invalid entries, and download submission files in single, CSV, or bulk ZIP formats.

Stakeholders

• Users: summerfest admins
• Upstream Dependencies: summerfest backend
• Downstream Consumers: admin users

Scope & Boundaries

• In Scope: Admin login flow, protected dashboard pages, Datathon submission management, Sistech submission management, authenticated file download proxy routes, UI shell shared across admin pages
• Out of Scope: Public registration forms, backend business logic, database schema ownership, legacy data migration, payment processing logic, creation of new submission data from the admin panel

⚙️ Architecture & Design

System Diagram

Architecture Decisions (ADRs)

• Language/Framework: TypeScript, React 19, React Router 7 with SSR enabled, Vite 6, tailwind CSS
• Database: PostgreSQL for relational data
• Communication: Synchronous via HTTP

💻Technical Specifications

API Documentation

Data Model/Schema

Project Structure

summerfest-admin-fe/
├── .github/                       # repository metadata and CI-related configuration
├── app/
│   ├── app.css                    # global stylesheet and shared visual tokens
│   ├── root.tsx                   # root document, metadata, and global route shell entrypoint
│   ├── routes.ts                  # file-based route registration via React Router flatRoutes
│   ├── components/
│   │   ├── context/
│   │   │   └── theme-provider.tsx # theme provider wrapper used by the app shell
│   │   ├── elements/              # custom product-specific UI building blocks
│   │   │   ├── Button/            # shared button component wrapper
│   │   │   ├── Card/              # card display wrapper
│   │   │   ├── Dropzone/          # drag-and-drop upload utility components
│   │   │   ├── FloatingButton/    # floating action button component
│   │   │   ├── Input/             # form field abstractions and styled inputs
│   │   │   ├── Layout/            # Navbar, Footer, and layout-related helpers
│   │   │   ├── Loader/            # loading state component
│   │   │   ├── Modals/            # modal dialogs for confirmation and UX flows
│   │   │   ├── Pagination/        # pagination component for submission tables
│   │   │   ├── SVG/               # inline SVG components
│   │   │   └── Stack/             # layout stack abstraction
│   │   ├── icons/                 # social and interface icon components
│   │   ├── ui/                    # reusable Radix/shadcn-style primitive components
│   │   ├── error.tsx              # shared error presentation component
│   │   ├── loading.tsx            # shared loading fallback component
│   │   └── utils/                 # frontend helper utilities for file, S3, and scroll behavior
│   ├── hooks/
│   │   ├── use-mobile.ts          # responsive state helper
│   │   ├── use-toast.ts           # toast state helper
│   │   └── useLogout.ts           # logout flow helper
│   ├── lib/
│   │   ├── auth.server.ts         # cookie handling and backend token verification
│   │   ├── download.ts            # browser-side download helpers
│   │   ├── fetch.server.ts        # server-side authenticated API fetch wrapper
│   │   ├── fetch.ts               # client-side API helper
│   │   ├── prisma.ts              # Prisma client bootstrap
│   │   ├── utils.ts               # shared utility helpers
│   │   └── generated/             # generated Prisma client artifacts
│   ├── modules/
│   │   ├── LoginModule/           # login page UI, loader, and action
│   │   ├── DashboardIndexModule/  # dashboard landing page UI, loader, and action
│   │   ├── DatathonModule/        # Datathon submission management UI and mutations
│   │   └── SistechModule/         # Sistech submission management UI and mutations
│   └── routes/
│       ├── _page.tsx              # shared public layout wrapper
│       ├── _page._index.tsx       # landing/login route
│       ├── _page.dashboard._index.tsx # dashboard home route
│       ├── _page.dashboard.datathon.tsx # Datathon admin route
│       ├── _page.dashboard.sistech.tsx  # Sistech admin route
│       ├── api.logout.tsx         # logout route that clears auth cookie
│       ├── api.datathon.submissions.$submissionId.download.tsx # single Datathon download proxy
│       ├── api.datathon.submissions.download-bulk.tsx          # bulk Datathon ZIP export route
│       ├── api.datathon.submissions.download-csv.tsx           # Datathon CSV export proxy
│       ├── api.sistech.submissions.$submissionId.download.tsx  # single Sistech download proxy
│       ├── api.sistech.submissions.download-bulk.tsx           # bulk Sistech ZIP export route
│       └── api.sistech.submissions.download-csv.tsx            # Sistech CSV export proxy
├── config/
│   ├── cdn.ts                     # CDN-related constants
│   ├── config.ts                  # runtime app configuration helpers
│   └── ulaskelas-cdn.ts           # additional CDN constant definitions
├── docs/
│   └── tech-doc.md                # technical documentation for this frontend
├── public/
│   └── favicon.ico                # static favicon asset
├── scripts/
│   └── generate-module-and-page.mjs # scaffolding helper for module/page generation
├── Dockerfile                     # container build definition
├── package.json                   # project manifest and npm scripts
├── pnpm-lock.yaml                 # dependency lockfile
├── react-router.config.ts         # React Router runtime/build configuration
├── tsconfig.json                  # TypeScript configuration
└── vite.config.ts                 # Vite build configuration

Components

Layer	Paths	Responsibility
App Configuration and Metadata	app/root.tsx, app/routes/_page.tsx, app/components/context/theme-provider.tsx, app/components/elements/Layout/*	Initializes the global admin shell, including global CSS, metadata, Google Fonts, favicon links, route-level error boundaries, theme provider wiring, shared navbar/footer layout, toast rendering, and logged-in user detection from the request cookie.
Authentication Entry Module	app/routes/_page._index.tsx, app/modules/LoginModule/*, app/lib/auth.server.ts	Handles the unauthenticated admin entry flow, including login form rendering, zod validation, backend authentication, admin_token cookie management, token verification against admin/verify-token/, and redirect into the protected dashboard.
Dashboard Landing Module	app/routes/_page.dashboard._index.tsx, app/modules/DashboardIndexModule/*	Renders the authenticated dashboard landing page, checks access state, and serves as the module selection entry point before admins move into Datathon or Sistech submission management.
Datathon Admin Module	app/routes/_page.dashboard.datathon.tsx, app/modules/DatathonModule/*	Handles the Datathon admin workflow, including paginated submission loading, client-side search across team and member data, verification toggles, deletion with confirmation, and triggering single-file, CSV, and bulk ZIP export flows.
Sistech Admin Module	app/routes/_page.dashboard.sistech.tsx, app/modules/SistechModule/*	Handles the Sistech admin workflow, including paginated submission loading, client-side search, server-driven filtering by program and path, deletion with confirmation, and triggering single-file, CSV, and bulk ZIP export flows.
UI Component Layer	app/components/elements/, app/components/ui/, app/components/icons/*	Provides the reusable presentation layer for the admin panel, including layout shell pieces, buttons, cards, inputs, pagination, modals, loaders, inline SVGs, and lower-level Radix-based primitives such as dialogs, tables, tabs, selects, toasts, and related interaction patterns.
Frontend Utility Layer	app/hooks/, app/components/utils/, app/lib/fetch.ts, app/lib/fetch.server.ts, app/lib/download.ts, app/lib/utils.ts	Centralizes shared frontend helpers such as logout flow, responsive state, toast state, scroll and file utilities, authenticated server-side API calls, generic client-side fetch helpers, and browser-side download handling with filename extraction from Content-Disposition.
Proxy Layer	app/routes/api.datathon.submissions.$submissionId.download.tsx, app/routes/api.datathon.submissions.download-csv.tsx, app/routes/api.datathon.submissions.download-bulk.tsx, app/routes/api.sistech.submissions.$submissionId.download.tsx, app/routes/api.sistech.submissions.download-csv.tsx, app/routes/api.sistech.submissions.download-bulk.tsx	Provides authenticated backend-facing download routes for the admin UI, including single submission downloads, CSV export proxies, and bulk ZIP generation that iterates paginated backend data, fetches related submission files, and assembles downloadable archives with jszip.
Configuration Layer	config/, app/lib/prisma.ts, app/lib/generated/	Stores runtime constants and environment-dependent configuration, while also containing generated client artifacts and supporting library setup that are kept separate from route and module UI logic.

☁️ Operational Playbook

Infrastructure

• Cloud Provider: Vercel
• Link: https://summerfest-admin-fe.vercel.app

Environment Variables

Key	Description	Default (Dev)	Sensitive?
API_URL	Backend staging API	https://stg.api.event.ristek.cs.ui.ac.id/api/	No
API_URL	Backend API	https://api.event.ristek.cs.ui.ac.id/api/	No

🙋Questions

🗒 List of frequently asked questions or question that need to be answered that is related to this initiative ..