SafeX — Real-Time Messaging for Internship Hiring

Real-time chat connecting Companies and Interns, with universal video & file sharing, per-user chat clearing, read receipts, online presence, typing indicators, and in-app + email notifications.

Features

• 🔐 Real authentication — bcrypt-hashed passwords, JWT sessions
• 👥 Role-based directory — Companies find Interns and vice versa
• 💬 Real-time messaging — WebSocket hub with instant auto-reconnect & real-time sync
• 🟢 Global online presence — Reciprocal live online status badges for both Companies and Interns
• 🎬 Video & universal file sharing — Native inline HTML5 video (.mp4, .mov, .webm) & audio (.mp3, .wav) players, images, documents, spreadsheets, code files, and archives up to 100MB
• 🗑️ Per-user Clear Chat — WhatsApp-style "Clear Chat for Me" capability with per-user cleared_at filtering
• 🚫 WhatsApp-style message deletion — Soft message deletion with high-contrast vibrant theme styling
• ✓✓ Read receipts & delivery status — Sent / Delivered / Read blue ticks
• ⌨️ Typing indicators — Real-time peer typing state
• 🔔 Notifications — In-app unread badges + best-effort email dispatch
• 📱 Responsive UI — Modern dark/light theme design system built with Lucide React icons

Tech stack

Backend: FastAPI · WebSockets · SQLAlchemy · PostgreSQL
Frontend: React · TypeScript · Vite · React Router · Lucide React
Infra: Docker Compose & Containerized Microservices

Getting started

git clone <this-repo-url>
cd safex-v2
docker compose up --build

• Frontend: http://localhost:5173
• API docs: http://localhost:8000/docs

Register two accounts (one Company, one Intern) in separate browser sessions, then use the + button in the sidebar to find and message each other.

🐳 Docker Deployment & Containerization

SafeX is fully containerized using Docker Compose for seamless single-command local development and production-ready deployments.

Multi-Container Architecture

Container Name	Service	Image / Base	Ports	Notes
safex_v2_db	Database	postgres:16-alpine	5432:5432	Includes pg_isready health check
safex_v2_backend	API / WebSockets	Python 3.11 / FastAPI	8000:8000	Depends on healthy DB container
safex_v2_frontend	UI Web App	Node.js / React + Vite	5173:5173	Hot-reloading development server

Key Docker Features

• Automated Health Checks & Dependencies: The FastAPI backend waits for the PostgreSQL database container to pass health checks (pg_isready) before launching, preventing database connection errors on startup.
• Persistent Data Storage:
  • db_data: Named Docker volume preserving PostgreSQL database tables across container restarts.
  • uploads_data: Named Docker volume persisting uploaded file attachments.
• Live Code Reloading: Code changes on local disk trigger automatic hot reloading inside backend and frontend containers.

Common Docker Commands

# Start all containers in detached mode (background)
docker compose up -d

# Rebuild images and start containers
docker compose up --build

# View real-time aggregated container logs
docker compose logs -f

# Inspect specific service logs (e.g. backend)
docker compose logs -f backend

# Stop all running containers
docker compose down

# Stop containers and wipe persisted volumes (reset database & uploads)
docker compose down -v

Environment variables

Variable	Default	Notes
DATABASE_URL	local Postgres	set by docker-compose.yml
JWT_SECRET	dev placeholder	change this in production
CORS_ORIGINS	http://localhost:5173	comma-separated list
MAX_UPLOAD_MB	100	maximum upload size in MB for video and file sharing
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASSWORD	unset	optional, enables real email notifications

Project structure

safex-v2/
├── docker-compose.yml
├── LICENSE
├── README.md
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── main.py              # FastAPI application entrypoint & auto-migrations
│       ├── db.py                # Database connection & session setup
│       ├── notifications.py     # In-app & email notification dispatch
│       ├── ws_manager.py        # WebSocket connection manager & hub
│       ├── core/                # Config, JWT authentication, password hashing
│       ├── models/              # User, Conversation, Message, Attachment, Notification
│       ├── schemas/             # Pydantic request/response validation models
│       └── routers/             # Auth, directory, chat REST & WebSocket endpoints
└── frontend/
    ├── Dockerfile
    ├── index.html
    ├── package.json
    ├── vite.config.ts
    └── src/
        ├── App.tsx              # Application router & layout structure
        ├── main.tsx             # Application entry point
        ├── components/          # Avatar, RoleBadge, FileIcon components
        ├── context/             # AuthContext session & user state management
        ├── features/chat/       # Chat window, sidebar, directory modal, WebSocket hooks
        ├── lib/                 # API client utilities
        └── styles/              # Design tokens and CSS stylesheets

API summary

• POST /api/auth/register — Register new Company or Intern account
• POST /api/auth/login — Authenticate and receive JWT session
• GET /api/auth/me — Get current user profile
• GET /api/users/directory?q= — Browse users of the opposite role
• POST /api/chat/conversations — Start or retrieve conversation with a peer
• GET /api/chat/conversations — List active conversations with unread counts & preview
• GET /api/chat/conversations/{id}/messages?after_id= — Fetch message history / catch-up
• DELETE /api/chat/conversations/{id}/messages — Clear chat history for the requesting user
• DELETE /api/chat/messages/{id} — Delete specific message with WhatsApp-style placeholder
• GET /api/chat/conversations/{id}/presence — Retrieve real-time peer presence state
• POST /api/chat/conversations/{id}/read — Mark conversation messages as read
• POST /api/chat/upload — Upload video, audio, image, or document attachment (up to 100MB)
• GET /api/chat/notifications/unread-count — Unread notification count badge
• WS /api/chat/ws?token= — Real-time WebSocket hub for messaging, presence, and typing state

Verification & Testing

• Backend: Pycompile validation and live API smoke tests (registration, auth, directory search, WebSocket realtime state).
• Frontend: TypeScript type check (tsc --noEmit) and Vite production build (vite build).

License

This project is licensed under the terms of the MIT License.