How omar-elhadi/marsai works
Purpose and Entry Points
Marsai Festival is a TypeScript monorepo for AI-film submission, jury review/voting, festival administration, and public award/gallery presentation. The React SPA starts at client/src/main.tsx and composes routes/UI in client/src/App.tsx. The Express API starts through server/src/index.ts; Vercel serverless adaptation is at server/api/index.ts.
Frontend Application Shell
The Vite/React client separates public, admin, and jury experiences. Layout and route protection enforce authenticated access before privileged views; localization is initialized centrally. Key paths: client/src/App.tsx, client/src/components/ProtectedRoute.tsx, client/src/contexts/AuthContext.tsx.
Submission and Film Lifecycle
Public submitters create and track films, including YouTube-based film content. Administrators review entries, update statuses, request changes, select finalists, and manage film details. This lifecycle spans client/src/pages/Submission/SubmissionForm.tsx, server/src/routes/film.routes.ts, and server/src/services/film.service.ts.
Identity, Roles, and Authorization
JWT authentication uses argon2-backed credentials and role-based authorization for Admin, Moderator, and Jury workflows. The client restores/session-checks user identity and calls dedicated auth APIs; the server authenticates requests before protected handlers. Paths: client/src/hooks/useAuth.ts, server/src/services/auth.service.ts, server/src/middlewares/auth.middleware.ts.
Jury Evaluation and Awards
Jury members access assigned/reviewable films and submit ratings/comments. Votes feed administrative selection and award-category/winner management, with public palmarès output. Core boundaries are client/src/pages/Jury/JuryDashboard.tsx, server/src/services/vote.service.ts, and server/src/services/award.service.ts.
API Layer and Persistence
Express routes delegate through controllers to domain services, with centralized validation and error handling. Prisma owns the relational MySQL schema and migrations; shared Zod schemas provide a cross-workspace validation contract. Paths: server/src/routes/vote.routes.ts, server/prisma/schema.prisma, packages/validators/src/index.ts.
Public Content and Supporting Services
The public site exposes gallery, award results, events/resources, jury information, newsletter signup, and configurable site settings. Backend services include newsletter/mail handling and gallery/settings data; frontend hooks isolate API consumption. Paths: client/src/pages/Gallery/Gallery.tsx, server/src/services/newsletter.service.ts, server/src/services/settings.service.ts.
Runtime and Deployment Boundaries
Development runs a React/Vite client (5173) and Express API (5000), backed by MySQL 8.4. Docker Compose supports local/production container deployment; frontend and serverless API can deploy as separate Vercel projects. Mail transport is environment-configured. Paths: docker-compose.yml, docker-compose.prod.yml, server/src/services/mail.service.ts.
Main entry points: vote.routes.ts Routes, controllers & validation · index.ts API entry · App.tsx App shell & routes · schema.prisma Prisma schema & migrations
Components 21
React client
Public, admin, and jury SPA.
- Vite entry
client/src/main.tsx - App shell & routes · Composes public, admin, and jury experiences.
client/src/App.tsx - Auth session · Restores and exposes the current user.
client/src/contexts/AuthContext.tsx - Protected routes · Restricts privileged views by authentication and role.
client/src/components/ProtectedRoute.tsx - Film submission
client/src/pages/Submission/SubmissionForm.tsx - Jury dashboard
client/src/pages/Jury/JuryDashboard.tsx - Public gallery
client/src/pages/Gallery/Gallery.tsx
Express API
HTTP API and domain services.
- API entry
server/src/index.ts - Routes, controllers & validation · Routes delegate requests through controllers with centralized validation and errors.
server/src/routes/vote.routes.ts - Authentication & RBAC · JWT authentication and role authorization for protected handlers.
server/src/middlewares/auth.middleware.ts - Credential service · Uses argon2-backed credentials and issues identity access.
server/src/services/auth.service.ts - Film lifecycle service · Manages submissions, review status, change requests, and finalists.
server/src/services/film.service.ts - Voting service · Records jury ratings and comments.
server/src/services/vote.service.ts - Awards service · Manages categories, winners, and palmarès output.
server/src/services/award.service.ts - Content services · Provides newsletter, settings, gallery, event, and resource data.
server/src/services/settings.service.ts - Mail transport · Environment-configured mail delivery.
server/src/services/mail.service.ts
Data contracts
- Shared Zod schemas · Cross-workspace request and data validation.
packages/validators/src/index.ts - Prisma schema & migrations · Owns relational schema and migrations.
server/prisma/schema.prisma - MySQL 8.4
Runtime & deployment
- Vercel API adapter · Adapts the API for serverless deployment.
server/api/index.ts - Docker Compose · Runs client, API, and MySQL locally or in production.
docker-compose.yml
Connections 29
- Vite entry → App shell & routes: mounts
- App shell & routes → Auth session: uses
- App shell & routes → Protected routes: guards views with
- App shell & routes → Film submission: routes to
- App shell & routes → Jury dashboard: routes to
- App shell & routes → Public gallery: routes to
- Auth session → API entry: checks session
- Film submission → API entry: submits and tracks films
- Jury dashboard → API entry: loads films and votes
- Public gallery → API entry: loads public content
- API entry → Routes, controllers & validation: dispatches requests
- Routes, controllers & validation → Shared Zod schemas: validates with
- Routes, controllers & validation → Authentication & RBAC: protects handlers
- Authentication & RBAC → Credential service: authenticates via
- Routes, controllers & validation → Film lifecycle service: film endpoints
- Routes, controllers & validation → Voting service: vote endpoints
- Routes, controllers & validation → Awards service: award endpoints
- Routes, controllers & validation → Content services: content endpoints
- Content services → Mail transport: sends newsletters
- Credential service → Prisma schema & migrations: persists users
- Film lifecycle service → Prisma schema & migrations: persists films
- Voting service → Prisma schema & migrations: persists votes
- Awards service → Prisma schema & migrations: persists awards
- Content services → Prisma schema & migrations: persists site content
- Prisma schema & migrations → MySQL 8.4: maps to
- Vercel API adapter → API entry: adapts
- Docker Compose → Vite entry: runs client
- Docker Compose → API entry: runs API
- Docker Compose → MySQL 8.4: runs database