WikINT Documentation

Technical documentation for WikINT, a collaborative academic materials platform for Telecom SudParis / IMT-BS students.

Stack: FastAPI + SQLAlchemy (Python) | Next.js + React (TypeScript) | PostgreSQL | Redis | MinIO | Meilisearch | Docker Compose

---

Architecture

System-level design, data model, and technology choices.

• System Overview -- Service topology, request lifecycle, auth flow, file upload flow, PR approval pipeline, SSE architecture
• Data Model -- ER diagram, all 17 tables, design patterns (soft deletes, polymorphic associations, self-referential trees, JSONB)
• Tech Stack -- Complete dependency inventory with versions and rationale

API (Backend)

FastAPI routers, services, and business logic.

• API Overview -- 3-layer architecture, dependency injection, error handling, pagination, post-commit job pattern
• Authentication -- Passwordless email login, JWT tokens, refresh flow, role hierarchy
• Browse & Directories -- Path resolution algorithm, directory tree, recursive CTEs
• Materials -- Material lifecycle, versioning, attachments, file types
• Pull Requests -- Batch operations, temp ID system, topological sort, voting, execution pipeline
• Annotations -- Threading model, SSE real-time updates, material-scoped events
• Comments -- Polymorphic comment system, target types
• Search -- Meilisearch indexing pipeline, split identifiers, multi-index search
• Upload -- Multipart upload flow, MIME magic byte detection, YARA + MalwareBazaar scanning
• Notifications -- Notification types, SSE delivery, Redis queue system
• Flags & Moderation -- Flag lifecycle, moderation actions, moderator powers
• Users -- Profiles, reputation, GDPR compliance, data export
• Admin -- Admin endpoints, access control, SQLAdmin dev interface

Web (Frontend)

Next.js pages, React components, and state management.

• Frontend Overview -- Page routing, Zustand stores, API client, layout, theming
• Authentication -- Login flow, useAuth hook, AuthGuard, token management
• Browse -- Directory listing, caching, material viewer integration
• Viewers -- 9 file viewers (PDF, code, image, video, audio, markdown, etc.)
• Pull Requests -- Staging system, review drawer, upload drawer, drag-and-drop
• Annotations -- Text selection tooltip, annotation threads, real-time updates
• Sidebar -- 5-tab sidebar (details, chat, annotations, edits, actions), responsive behavior
• Profiles -- Profile pages, contributions, reputation, settings
• Admin Pages -- Dashboard, user management, flag review, PR queue
• Notifications -- Multi-tab SSE coordination, navbar bell, notification page

Infrastructure

Docker services, configuration, and operational details.

• Infrastructure Overview -- Service topology, startup order, health checks, prod vs dev
• Database (PostgreSQL) -- Connection pool, session management, schema, SQL views
• File Storage (MinIO) -- S3 client, presigned URLs, file organization, malware scanner integration
• Search Engine (Meilisearch) -- Index setup, document structure, typo tolerance, reindexing
• Caching & Queues (Redis) -- ARQ queue, rate limiting, token blacklist, SSE queues
• Reverse Proxy (Nginx) -- Routing, TLS, security headers, certbot
• Background Workers (ARQ) -- On-demand jobs, cron schedule, job dispatch pattern

Guides

Step-by-step instructions for common operations.

• Local Development Setup -- Prerequisites, quick start, hot reloading, useful commands
• Deployment -- Production setup, TLS certificates, backups, monitoring
• CLI Reference -- seed, reindex, gdpr-cleanup, year-rollover commands
• Troubleshooting -- Common issues with startup, runtime, and data

Configuration

• Environment Variables -- Complete reference for all .env settings