AntiRecurso

AntiRecurso is the web frontend for NEI ISEP's exam-preparation platform. It gives students a browser-based interface to practice subject-specific exams, review results, track rankings, browse study notes, and access profile and admin features through a hosted authentication flow.

Key Features

• Subject-based exam practice with multiple answering modes
• Scoreboards and personal score tracking
• Protected notes area for authenticated users
• Hosted authentication flow backed by NextAuth and Zitadel/AuthNEI
• Admin dashboard for activity, comments, reports, notes, and users
• Cookie consent, changelog popup, theming, and responsive UI

Tech Stack

• Runtime: Node.js 20.9+ and pnpm 9
• Framework: Next.js 16 App Router
• UI: React 19, Tailwind CSS, Framer Motion
• Auth: NextAuth 4 with the Zitadel provider
• Validation: Zod
• Charts: Chart.js and react-chartjs-2
• Data Fetching: native fetch plus SWR where needed
• Language: TypeScript

Architecture Overview

This repository is a frontend application, not the full AntiRecurso platform.

• The UI is rendered by Next.js in src/app.
• Authentication is handled through NextAuth in src/lib/auth.ts with a hosted Zitadel/AuthNEI login flow.
• Business data such as users, subjects, exams, scores, notes, and admin stats comes from an external backend API defined by NEXT_PUBLIC_BASE_URL.
• Authenticated requests can be proxied through src/app/api/backend/[...path]/route.ts, which forwards the logged-in user's access token to the upstream backend.
• Admin routes are guarded by src/proxy.ts, which checks the session token and validates backend admin access before allowing the request through.

Main Route Groups

• / - landing page
• /exams - subject picker for exam sessions
• /exams/[id]/answer - exam answering flow
• /exams/[id]/review - answer review flow
• /scoreboard - subject picker for rankings
• /notes - subject picker for study notes
• /profile - authenticated user profile and previous results
• /admin - protected admin dashboard
• /login, /register, /reset-password - hosted auth entry points

Authentication Notes

This codebase no longer supports password-based local auth forms.

• POST /api/auth/login
• POST /api/auth/register
• POST /api/auth/reset-password
• POST /api/auth/reset-password/send

These endpoints intentionally return 410 Gone and direct users to the hosted AuthNEI flow instead.

Repository Structure

.
├── assets/                 Legacy README screenshots and static media
├── public/                 Favicons, logos, images, manifest, robots.txt
├── scripts/                Utility scripts
├── src/
│   ├── app/                App Router pages, layouts, route handlers
│   ├── components/         UI components by domain
│   ├── config/             App constants and feature flags
│   ├── contexts/           React context providers
│   ├── hooks/              Custom React hooks
│   ├── lib/                Auth and server-side session helpers
│   ├── schemas/            Zod schemas
│   ├── services/           Backend-facing service functions
│   ├── styles/             Global and shared styles
│   ├── types/              TypeScript domain types
│   └── utils/              Shared helpers
├── .env.example            Sample environment configuration
├── next.config.js          Next.js configuration
├── package.json            Scripts and dependencies
└── tailwind.config.js      Tailwind setup

Prerequisites

Install the following before running the project locally:

• Node.js >=20.9.0
• pnpm >=9
• Access to a running AntiRecurso backend API
• Access to a Zitadel/AuthNEI client configuration for local login testing

If you use nvm, the repository includes .nvmrc.

Getting Started

1. Clone the repository

git clone <your-fork-or-origin-url>
cd antirecurso

2. Select the Node version

nvm use

If you do not use nvm, install a compatible Node.js version manually.

3. Install dependencies

The project enforces pnpm via only-allow.

pnpm install

4. Create your local environment file

Copy the example file:

cp .env.example .env.local

Next.js also works with .env, but .env.local is the preferred local-development file.

5. Configure environment variables

At minimum, define the variables below before starting the app.

Variable	Required	Description
NEXT_PUBLIC_BASE_URL	Yes	Base URL of the AntiRecurso backend API. This is required by the frontend code but is not currently present in .env.example.
AUTH_SECRET	Yes	NextAuth secret used to sign and decrypt session tokens.
AUTH_ISSUER_URL	Yes	Zitadel/AuthNEI issuer URL.
AUTH_CLIENT_ID	Yes	OAuth client ID for the hosted login flow.
AUTH_CLIENT_SECRET	Usually	OAuth client secret for the Zitadel provider.
AUTH_SCOPES	No	Defaults to openid email profile.
AUTH_POST_LOGOUT_REDIRECT_URI	Recommended	Redirect target after logout. Defaults to / if omitted.
AUTH_DEBUG	No	Set to true to enable verbose auth logging.

The sample file also contains:

• APP_BASE_URL
• AUTH_REDIRECT_URI

Those values may still be useful for external auth-provider setup, but they are not referenced directly by this frontend codebase.

Example local configuration:

NEXT_PUBLIC_BASE_URL=http://localhost:4000
AUTH_SECRET=replace-with-a-long-random-secret
AUTH_ISSUER_URL=https://auth.example.com
AUTH_CLIENT_ID=replace-with-your-client-id
AUTH_CLIENT_SECRET=replace-with-your-client-secret
AUTH_SCOPES=openid email profile
AUTH_POST_LOGOUT_REDIRECT_URI=http://localhost:3000
AUTH_DEBUG=false

6. Start the development server

pnpm dev

The app runs on http://localhost:3000 by default.

Available Scripts

Defined in package.json:

• pnpm dev - start the Next.js development server
• pnpm build - create a production build
• pnpm start - start the production server
• pnpm lint - run ESLint

Development Notes

Backend Dependency

Most meaningful pages depend on a live backend:

• subject lists are fetched from the API
• profile data is fetched from /user
• scoreboard data comes from backend score endpoints
• admin pages call protected admin endpoints

Without a reachable backend and valid auth configuration, the app will render incompletely or redirect away from protected routes.

Session Model

The app uses a JWT session strategy:

• NextAuth stores the upstream access token and ID token in its JWT
• server helpers in src/lib/server-auth.ts read those tokens from cookies
• authenticated server components fetch user data from the backend before rendering
• the /api/backend/* proxy forwards the bearer token to the upstream API

Theming and Global UX

The root layout in src/app/layout.tsx wires up:

• global styles
• the top navigation bar
• auth context
• theme provider
• changelog popup
• cookie consent banner

Deployment Guidance

No deployment manifests such as Dockerfile, vercel.json, render.yaml, or fly.toml are currently committed in this repository. That means deployment is flexible, but you need to provide the surrounding infrastructure yourself.

For production you need:

• a Node-compatible host capable of running next build and next start
• all auth-related environment variables
• a reachable backend API URL for NEXT_PUBLIC_BASE_URL
• a correctly configured callback and logout setup in Zitadel/AuthNEI

A typical production flow is:

pnpm install --frozen-lockfile
pnpm build
pnpm start

If you deploy behind a reverse proxy or managed platform, ensure:

• HTTPS is enabled
• your auth issuer accepts the production callback URL
• AUTH_POST_LOGOUT_REDIRECT_URI matches the deployed frontend URL

Troubleshooting

Login succeeds but the app acts logged out

Check:

• AUTH_SECRET
• AUTH_ISSUER_URL
• AUTH_CLIENT_ID
• AUTH_CLIENT_SECRET
• whether the issued access token is expired

The auth helper marks expired tokens with AccessTokenExpired, and protected routes will reject them.

Pages fail with missing data

Check:

• NEXT_PUBLIC_BASE_URL
• backend availability
• whether the backend accepts the forwarded bearer token

Admin routes redirect to the homepage

That usually means one of the following:

• there is no valid session token
• the upstream access token expired
• the backend /admin check returned a non-200 status

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for contribution workflow and expectations.

Security

If you discover a vulnerability, read SECURITY.md before disclosing it.

License

This project is licensed under the GNU General Public License v3.0. See LICENSE.

Contact

• Email: support.antirecurso@nei-isep.org
• Public site: https://antirecurso.nei-isep.org