Skip to content

README.md

Latest commit

 

History

History
231 lines (200 loc) · 11.4 KB

README.md

File metadata and controls

231 lines (200 loc) · 11.4 KB
Raw

Concord

This project has been created as part of the 42 curriculum by @coffor, @fallan, @ichpakov and @lferro.

Description

Concord is our ft_transcendence project at Ecole 42 Lausanne: a Discord-like web application with servers, channels, direct messages, voice channels, friend management, role-based moderation, and real-time presence.

Features list

Feature Details
Authentication Keycloak login/exchange/logout, token verification, protected routes
User profile me profile, bio update, avatar upload
Server lifecycle discover, create, join, leave, rename, delete servers
Moderation and roles member listing, promote/demote, kick, ban/unban
Channel management create/rename/delete text and voice channels
Messaging server text channels + DM channels + realtime message fan-out
Friends add/remove friends, request accept/reject/cancel, friend updates
Presence online/offline status over websocket events
Voice channels Socket.IO room signaling + PeerJS/WebRTC peer connection flow for live voice, including join/leave events and in-call audio controls
Analytics dashboard dedicated analytics API + UI, realtime updates, and CSV/PDF export flows
Monitoring metrics endpoints and exporters on backend and infra, dashboards, and alerting
API documentation Swagger docs for HTTP + generated socket docs

Team information

  • Product Owner: Facoleur (@lferro)
    • leading product scope definition
    • keeping an overview on the project
    • managing integration priorities
  • Project Manager: Francis (@fallan)
    • organizing tasks
    • defining team workflows
    • organizing and running meetings
  • Technical Lead: Ilia (@ichpakov)
    • defining the technical architecture
    • making technology stack decisions
  • Developers: all team members

Individual contributions

Facoleur (@lferro)

  • led most frontend work (navigation, server/channel UI, chat screens, member/friend interactions)
  • implemented voice-channel client flow and major realtime UI integration
  • contributed to backend/websocket integration and deployment fixes
  • challenge handled: stabilizing voice + websocket behavior behind HTTPS/reverse proxy

Chika (@coffor)

  • implemented large parts of backend routes, handlers, schemas, and services
  • integrated auth flows and endpoint contract cleanup
  • built the largest share of the srcs/test integration tests
  • challenge handled: backend refactor while keeping endpoint behavior testable

Ilia (@ichpakov)

  • contributed initial architecture structure and technical direction documentation
  • implemented an analytics service with realtime update service wiringe and a frontend dashboard structure with reusable chart/stat blocks, filter/header sections, and a realtime client hook
  • added data export for analytics outputs (CSV/PDF)
  • challenge handled: integrating a new analytics pipeline into an already evolving stack, while keeping API contracts stable

Francis (@fallan)

  • drove PM workflow docs and coordination artifacts (Contributing, meeting notes, planning docs)
  • added monitoring hooks to backend and infrastructure components
  • created visualizations, alerts and notifications based on monitored events
  • challenge handled: integrating monitoring hooks within various services

Project management

  • Work was organized asynchronously through GitLab issues + merge requests.
  • Conventional commit naming was used for issues and commits (feat, fix, docs, etc.).
  • Reviews were performed through merge requests with designated reviewers.
  • Team communication used Discord + regular sync meetings.
  • Team conventions and workflow rules are documented in org/Contributing.md.

Modules

Module Type Points Why chosen How it is implemented Contributors
Use a framework for frontend and backend Major 2 Keep one modern TypeScript stack end to end and speed up team delivery. Next.js frontend + Fastify backend. Facoleur, Chika
Real-time features via WebSockets Major 2 A Discord-like app requires live updates without refresh. Socket.IO service, realtime events, presence, message fan-out. Facoleur, Chika
Allow users to interact Major 2 Social interaction is the core product value. Chat, profile, friends, and DMs. Facoleur, Chika
Standard user management and authentication Major 2 Identity and access control are mandatory foundations. Profile update, avatar upload, auth middleware, Keycloak integration. Chika, Facoleur
Organization system Major 2 Server-centric organization model is central to the app. Servers as organizations with membership and role-based actions. Facoleur, Chika
Backend as microservices Major 2 Separate HTTP and realtime responsibilities to keep services maintainable. Dedicated backend API + websocket service + shared Redis pub/sub. Facoleur, Chika, Ilia
Advanced analytics dashboard with data visualization Major 2 Provide product/usage insight beyond core chat features. Dedicated analytics API + UI, interactive charts, realtime updates, CSV/PDF export. Ilia
Monitoring with Prometheus and Grafana Major 2 Observe and debug a multi-service deployment faster. Prometheus scraping, Grafana dashboards, alert rules, exporters. Francis
Use an ORM for the database Minor 1 Standardize persistence access and reduce SQL boilerplate. Prisma schema/client in backend. Chika
Custom design system Minor 1 Keep UI components consistent and reusable across screens. Reusable UI primitives. Facoleur
File upload and management Minor 1 Required for server logos and user avatars with safe handling. Validated avatar/server-logo upload pipeline. Facoleur, Chika

Total: 19 points.

Technical stack

The project is containerized and split into dedicated services:

  • Frontend (Next.js)
  • Backend API (Fastify)
  • Realtime gateway (Socket.IO)
  • Peer signaling server (peerjs/peerjs-server)
  • Analytics API + dashboard module (Fastify + React/Vite)
  • Auth provider (Keycloak)
  • Data layer (PostgreSQL, Redis)
  • Reverse proxy (Nginx)
  • Monitoring (Prometheus, Grafana, exporters)

Frontend

  • Next.js 16 + React 19 + TypeScript
  • @tanstack/react-query for server-state/cache workflows
  • zustand for voice channel state and global websocket state
  • next-intl for i18n scaffolding
  • PeerJS + WebRTC client flow for voice channels
  • mdx-js for rendering mdx files (legal pages)
  • hark for voice detection
  • shadcn for base UI compnents and tailwind css for styling
  • zod for schema validation
  • custom reusable UI layer in srcs/frontend/src/components/ui

Backend and Realtime

  • Fastify API (srcs/backend/app)
  • Socket.IO for realtime service (srcs/websocket/app)
  • PeerJS server (docker service) for WebRTC peer discovery/signaling, exposed through nginx at /peerjs
  • Keycloak for authentication and identity flows
  • Redis pub/sub and presence state

Analytics

  • Dedicated analytics backend service (Fastify, TypeScript) for summary, timeseries, top channels/users, channel share, and export endpoints
  • Dedicated analytics dashboard UI (React + Vite) for interactive charts and filtered views
  • Realtime analytics updates through websocket integration
  • Export flows in CSV/PDF/JSON

Data

  • PostgreSQL database as source of truth
  • Prisma ORM/client generation for backend persistence

Devops and observability

  • Docker Compose orchestration (dev and prod profiles)
  • Nginx reverse proxy + TLS termination (HTTPS on :443) with path-based routing to frontend/backend/websocket/keycloak/peerjs
  • Prometheus + service exporters (postgres_exporter, redis_exporter, nginx_exporter, cAdvisor) monitoring, Grafana visualization and alerts

Justification

  • Fastify + Next.js keep a modern TypeScript stack end to end.
  • Keycloak externalizes authentication complexity (token lifecycle, identity provider capabilities).
  • Redis + Socket.IO provide low-latency cross-service event distribution.
  • Docker Compose made local integration and service isolation manageable for a school team project.

Database schema

Main schema source: srcs/backend/app/prisma/schema.prisma

erDiagram
    User ||--o{ Message : writes
    User ||--o{ Request : sends
    User ||--o{ Request : receives
    User ||--o{ ServerRole : has
    User ||--o{ ServerBan : can_be
    User ||--o{ UserBlock : blocks
    Server ||--o{ Channel : contains
    Server ||--o{ ServerRole : has_roles
    Server ||--o{ ServerBan : has_bans
    Channel ||--o{ Message : stores
    User }o--o{ Channel : joins_dm
Loading

Key entities and fields:

  • User: id, username, email, optional bio, optional avatar
  • Server: id, name, optional logo
  • Channel: id, optional name, type (text, voice, dm), optional serverId
  • Message: id, text, userId, channelId, createdAt
  • ServerRole: user/server role (admin, user)
  • ServerBan, UserBlock, Request: moderation + friendship workflow data

Instructions

Installation and setup

Tools needed to run the project:

  • GNU Make
  • Docker
  • Docker Compose

Environment configuration:

  • Use srcs/.env with your own secrets and URLs.
  • To set the production or dev mode, use the NODE_ENV=production/dev. In production, change the KC_START_CMD variable (cf. line 8-11 in .env.example).
  • Replace default credentials before sharing/deploying.

How to run

From the repository root:

Development mode:

make

Production mode:

make prod

Service endpoints (dev defaults)

  • App: https://localhost:1443
  • API docs (Swagger): https://localhost:1443/api/docs
  • Socket docs (AsyncAPI static export): https://localhost:1443/api/socket/docs
  • PeerJS signaling endpoint (proxied): https://localhost:1443/peerjs
  • Keycloak admin: https://localhost:1443/admin/
  • Keycloak host port: http://localhost:18080
  • Monitoring (Grafana): http://localhost:3002

Note:

  • HTTPS uses a self-signed certificate in dev; your browser will warn on first access.
  • HTTP traffic is redirected to HTTPS by nginx.

Useful make targets

make logs SERVICE=backend
make ps
make restart SERVICE=frontend
make clean
make fclean
make prod-ps
make prod-logs

Resources

Project documents

  • Build workflow: docs/BUILD.md
  • Feature scope: docs/Features.md
  • Incident triage using monitoring: docs/monitoring-incident-triage-runbook.md
  • Architecture notes: docs/architecture/ARCHITECTURE.en.md

External references

AI usage

AI was used as a productivity tool for repetitive tasks and drafting support (debugging assistance, documentation drafts, and technical research), with manual team review before merge.