Animersion

Animersion is a privacy-first MERN anime discovery application. A short taste quiz produces ranked, explainable recommendations, and an optional public MyAnimeList username filters out titles already on that list. The site also presents featured anime, current news, and paginated airing and popularity rankings.

This portfolio project deliberately has no user accounts. It demonstrates a full React, Express, Node, and MongoDB architecture without collecting data that the product does not need.

What makes it a MERN application

React + Vite (browser)
        |
        | /api/home, /api/rankings, /api/recommendations
        v
Express + Node (server)
        |
        +---- Jikan / MyAnimeList / AniList (public anime data)
        |
        +---- MongoDB Atlas (optional, expiring public-data cache only)

Contact form ---- EmailJS ---- project owner's inbox

• MongoDB stores only cached public anime API responses with automatic expiry.
• Express exposes typed API routes, request validation boundaries, security headers, structured errors, and privacy-conscious request logs.
• React provides the responsive discovery interface, quiz, recommendations, rankings, legal pages, and contact form.
• Node.js runs the recommendation engine, upstream fallbacks, MAL history filtering, and optional database integration.

Privacy boundaries

Animersion does not create accounts or store visitor profiles. MongoDB never receives contact messages, MAL usernames, quiz answers, recommendation requests, IP addresses, or browser identifiers. A supplied MAL username and quiz answers exist only while the current recommendation request is processed.

The contact form remains client-side and sends the submitted name, email, and message through EmailJS to the configured inbox. Animersion does not copy that submission into MongoDB. The exact visitor-facing disclosures are in /privacy and /terms.

Application logs contain only a random request ID, HTTP method, path without query values, response status, and processing time. Hosting infrastructure can still process ordinary connection metadata under its own policies.

Recommendation flow

The quiz collects popularity, content-safety, demographic, genre, viewing-mood, episode-length, airing-status, and studio preferences. The API:

1. validates and normalizes the submitted choices;
2. builds focused and broad Jikan candidate searches;
3. reads the optional public MAL list for this request only;
4. removes duplicates, unsafe titles, and already-listed anime;
5. scores the remaining candidates deterministically; and
6. returns ten matches with human-readable reasons.

Jikan is the default read-only MyAnimeList data source. When MAL_CLIENT_ID is configured, the official MAL API improves coverage for unusually large public lists. Rankings automatically fall back to AniList if Jikan is unavailable.

Local development

Requirements

• Node.js 24 or newer
• npm
• MongoDB is optional

Install and start both Vite and Express:

npm install
npm run dev

• Web app: http://localhost:3000
• Express API: http://localhost:3001
• Health check: http://localhost:3001/api/health

Vite proxies /api requests to Express during local development. Copy .env.example to .env.local and fill only the services you want:

PORT=3001
MONGODB_URI=
MONGODB_DATABASE=animersion
MAL_CLIENT_ID=
VITE_EMAILJS_SERVICE_ID=
VITE_EMAILJS_TEMPLATE_ID=
VITE_EMAILJS_PUBLIC_KEY=

The recommendations, rankings, news, and carousel work without MongoDB, MAL credentials, or EmailJS. MongoDB adds a shared cache, the MAL client ID improves large-list coverage, and the three EmailJS values enable the contact form.

MongoDB Atlas: manual setup

Nothing needs to be inserted manually and no user collection is created.

1. Create an Atlas project and a free cluster.
2. Under Database Access, create a dedicated database user. Prefer a role limited to readWrite on the animersion database rather than an account shared with another project.
3. Under Network Access, allow your current IP for local development.
4. For Vercel deployment, choose the narrowest network rule your hosting plan supports. Hobby/serverless deployments generally do not have a stable outbound IP; the practical fallback is 0.0.0.0/0 with a unique strong database password and the database-limited role. A hosting option with static egress lets you use a narrower allowlist.
5. Select Connect → Drivers, copy the mongodb+srv://... connection string, replace its password placeholder, and set it as MONGODB_URI in .env.local and in the deployment environment settings.
6. Optionally set MONGODB_DATABASE=animersion. On first successful API cache write, Mongoose creates the anime_api_cache collection and its TTL index automatically.

If Atlas is missing or unreachable, /api/health reports the database state and the application continues with an in-memory cache.

API surface

Endpoint	Method	Purpose	Persistent visitor data
/api/health	GET	Service/database status and privacy contract	None
/api/home	GET	Featured, airing, popular, and news feed	Public response may be cached
/api/rankings	GET	Ten-item airing or popularity page	Public response may be cached
/api/recommendations	POST	Quiz scoring and optional MAL filtering	Never cached or stored

Verification

npm run typecheck
npm test
npm run test:recommendations
npm run build
npm audit

GitHub Actions runs type checking, UI/API tests, recommendation tests, and the production build for pushes and pull requests.

Vercel development and deployment

The repository includes api/index.ts as the serverless Express entry point and vercel.json for API and SPA rewrites. To reproduce Vercel locally:

npm install --global vercel
vercel login
vercel dev

For deployment, add the optional variables in Project Settings → Environment Variables, then run vercel for a preview or vercel --prod for production. Do not commit .env.local or the MongoDB connection string.

The Express process also supports conventional Node hosting: build with npm run build, set NODE_ENV=production, and run npm start.

Project structure

src/                 React UI, routes, policies, and component tests
server/              Express app, Mongo connection/cache, server tests
api/                 Typed recommendation/data services and Vercel entry
.github/workflows/   Continuous integration
vercel.json          Vercel routing and build configuration

Legal note

The included Terms and Privacy pages accurately describe this implementation but are project documentation, not legal advice. Have qualified counsel review them before turning Animersion into a commercial service or materially changing its data practices.