brief-20/docs/PROJECT_OVERVIEW.md
Avnyr f6f0888bd7 docs: add comprehensive project documentation files
Added detailed documentation files, including project overview, current status, specifications, implementation guide, and README structure. Organized content to improve navigation and streamline project understanding.
2025-05-15 17:08:53 +02:00

5.1 KiB

Comprehensive Project Overview

Introduction

This document provides a comprehensive analysis of the "Application de Création de Groupes" project, examining its architecture, technologies, features, and implementation details.

Project Purpose

The application is designed to facilitate the creation and management of groups of people based on various criteria. It allows users to create projects, add people with different attributes, and organize them into groups either manually or automatically using balancing algorithms.

Architecture Overview

The project follows a modern full-stack architecture with clear separation between frontend and backend:

Frontend (Next.js)

  • Uses Next.js with App Router pattern
  • Implements ShadcnUI for consistent UI components
  • Utilizes SWR for data fetching with caching
  • Implements real-time updates using Socket.IO client
  • Follows a component-based architecture with custom hooks

Backend (NestJS)

  • Built with NestJS framework for scalable server-side applications
  • Uses PostgreSQL with DrizzleORM for database operations
  • Implements OAuth 2.0 with GitHub for authentication
  • Uses JWT for session management
  • Provides WebSocket support via Socket.IO for real-time collaboration
  • Follows modular architecture with clear separation of concerns

Database

  • PostgreSQL with DrizzleORM
  • Well-defined schema with proper relationships
  • Optimized data types and indexing strategy
  • Support for migrations

Communication

  • REST API for CRUD operations
  • WebSockets for real-time updates and collaboration
  • JWT-based authentication for securing both REST and WebSocket endpoints

Key Features

  1. User Authentication

    • OAuth 2.0 with GitHub
    • JWT-based session management
    • Role-based access control
  2. Project Management

    • Create, read, update, delete projects
    • Associate tags with projects
    • Track project history
  3. Person Management

    • Add people with various attributes (technical level, gender, language skills, etc.)
    • Tag people for easier categorization
    • Track person attributes
  4. Group Creation

    • Manual creation via drag-and-drop interface
    • Automatic creation using balancing algorithms
    • Real-time collaboration between users
  5. Real-time Collaboration

    • See changes made by other users in real-time
    • Notifications for important events
    • Room-based communication for project-specific updates

Implementation Details

Authentication Flow

The authentication flow uses OAuth 2.0 with GitHub as the identity provider:

  1. User clicks "Login with GitHub"
  2. User is redirected to GitHub for authorization
  3. GitHub redirects back to the application with an authorization code
  4. Backend exchanges the code for an access token
  5. Backend retrieves user information from GitHub
  6. Backend creates or updates the user in the database
  7. Backend generates JWT tokens (access and refresh)
  8. Frontend stores the tokens and uses them for subsequent requests

Database Schema

The database schema includes the following main entities:

  1. Users - Storing user information
  2. Projects - Storing project information
  3. Persons - Storing information about people to be placed in groups
  4. Groups - Storing information about created groups
  5. Tags - For categorizing persons and projects
  6. Relation tables - For many-to-many relationships

WebSocket Implementation

The WebSocket implementation uses Socket.IO for real-time communication:

  1. Authentication using JWT
  2. Room-based communication for project-specific updates
  3. Event-based messaging for different types of updates
  4. Proper connection and disconnection handling

Deployment

The application is containerized using Docker, with separate containers for:

  1. Frontend (Next.js)
  2. Backend (NestJS)
  3. PostgreSQL database

Development Workflow

The project uses:

  • PNPM for package management
  • ESLint and Prettier for code quality
  • TypeScript for type safety
  • Jest for testing
  • Docker for containerization
  • Drizzle for database migrations

Security Considerations

The application implements several security measures:

  1. OAuth 2.0 for secure authentication
  2. JWT with short-lived access tokens and refresh tokens
  3. CORS configuration to prevent unauthorized access
  4. Input validation using class-validator
  5. Protection against common attacks (CSRF, XSS, SQL injection)
  6. GDPR compliance features

Performance Optimization

The application is optimized for performance:

  1. Efficient database schema with proper indexing
  2. Optimized data types for reduced storage requirements
  3. Caching strategies for frequently accessed data
  4. Lazy loading of components and data

Conclusion

The "Application de Création de Groupes" is a well-designed, modern web application that follows best practices in software development. It provides a comprehensive solution for creating and managing groups of people, with a focus on user experience, security, and performance.

The clear separation between frontend and backend, the use of modern technologies, and the implementation of real-time collaboration features make it a robust and scalable application that can be extended with additional features in the future.