A modern, privacy‑respecting chat platform built with Next.js, Tailwind CSS, and TypeScript. Hackloumi Chat delivers reliable 1‑to‑1 and group messaging, a sleek web experience, and a self‑contained deployment model that runs just as happily on a laptop as it does in the cloud.
| Category | Highlights |
|---|---|
| Registration | Instant sign‑up with just a username and double‑entered password—no emails or external identity providers. |
| Contacts | Mutual contact lists: adding someone automatically sends a request they must accept. Remove contacts any time. |
| Direct Chats | Persistent, searchable history for all 1‑to‑1 conversations with at‑least‑once delivery guarantees. |
| Group Chats | Up to 300 participants per room, with searchable history, owner‑managed member list, and graceful exit. |
| Media & Rich Text | Send images plus bold and italic text with markdown‑style shortcuts. |
| Reactions | Leave emoji reactions on any message. |
| Contact Visibility | View profile cards for contacts you know or fellow chat participants. |
| Deep Links | Stable URLs that resolve to any user or group chat — perfect for bookmarks and sharing. |
| Performance Tooling | Built‑in load‑test utility to validate throughput targets (≤ 50 msg s⁻¹). |
Hackloumi Chat features a sophisticated black and white design system that prioritizes clarity, elegance, and modern user experience principles. The interface embraces minimalism while maintaining full functionality and accessibility.
| Element | Color | Usage |
|---|---|---|
| Primary Background | #000000 (Pure Black) |
Main application background |
| Content Areas | #0a0a0a (Zinc-950) |
Cards, modals, and content containers |
| Secondary Areas | #18181b (Zinc-900) |
Sidebar, input fields, and secondary content |
| Borders | #27272a (Zinc-800) |
Subtle element separation |
| Primary Text | #ffffff (Pure White) |
Headings and primary content |
| Secondary Text | #a1a1aa (Zinc-400) |
Labels, metadata, and secondary content |
| Accent Actions | #ffffff (White on Black) |
Primary buttons and call-to-action elements |
- Font Family: Inter with system fallbacks (
-apple-system,BlinkMacSystemFont,Segoe UI,Roboto) - Font Weight: Light (300) for elegance and readability
- Letter Spacing: Wide tracking for modern, spacious feel
- Text Cases: Strategic use of UPPERCASE for headings and labels
- Anti-aliasing: Smooth rendering across all devices
.btn-primary /* White background, black text, primary actions */
.btn-secondary /* Dark background, white border, secondary actions */
.btn-ghost /* Transparent with subtle hover states */.card /* Dark containers with subtle borders */
.sidebar /* Navigation areas with consistent spacing */
.input-field /* Form inputs with focus states */.message-bubble-sent /* White bubbles for sent messages */
.message-bubble-received /* Dark bubbles for received messages */
.contact-item /* Clean contact list items with hover states */- Transitions: 200ms duration for all state changes
- Hover States: Subtle color shifts maintaining contrast
- Focus States: White borders for keyboard navigation
- Active States: Visual feedback for user interactions
- Mobile-First: Designed for all screen sizes
- Touch-Friendly: Adequate touch targets (44px minimum)
- Readability: High contrast ratios for accessibility
- Performance: Minimal CSS footprint with Tailwind optimization
- Scrollbars: Dark themed with subtle handles
- Text Selection: White on black for consistency
- Loading States: Minimal indicators matching theme
- Error Messages: Dark red variants maintaining aesthetic
The design system follows these core principles:
- Clarity Over Decoration: Every element serves a functional purpose
- Consistent Spacing: Systematic padding and margins using Tailwind scale
- Accessible Contrast: WCAG AA compliant color combinations
- Smooth Interactions: Purposeful animations that enhance UX
- Scalable Architecture: Component-based system for easy maintenance
This design approach creates a professional, modern interface that focuses user attention on conversations while providing an elegant, distraction-free environment for communication.
- Browser (Next.js front‑end) establishes a WebSocket for real‑time delivery; falls back to long‑polling whenever WebSockets are blocked.
- Realtime Gateway (Node.js / Socket.IO) processes commands, enforces security, and writes durable events.
- PostgreSQL stores all domain entities (users, contacts, messages, groups) in ACID‑compliant tables.
- Search Index (PG full‑text) enables fast lookup across conversations.
flowchart TD
Client[Web UI] -- WebSocket / HTTP --> API[Realtime & REST API]
API -- SQL --> DB[(PostgreSQL)]
API -- Events --> WS[Socket Broadcast]
subgraph Persistence
DB
end
Mermaid diagrams render directly on GitHub.
- At‑Least‑Once Delivery – acknowledgements travel back to the sender once the server commits the message, ensuring no silent drops.
- Crash‑Safe Storage – WAL‑backed PostgreSQL with automatic recovery; chat records survive container restarts.
- Reconnect Resume – missed events are replayed after connectivity loss using incremental cursors.
| Metric | Design Target |
|---|---|
| Concurrent users | 500 – 1 000 |
| Write throughput | ≤ 50 messages s⁻¹ (aggregated) |
| Group fan‑out | Server relays each group post to all online members without duplicates |
These numbers fit comfortably inside one AWS Fargate task with headroom for spikes.
+--------------------------+
| Amazon ALB (HTTPS) |
+-----------+--------------+
| 80 / 443
+-----------v--------------+
| Fargate Service (ECS) |
| • Next.js SSR & API |
| • Socket.IO Gateway |
| • Embedded PostgreSQL |
+-----------+--------------+
| 5432 (local only)
+-------------------- (optional) EFS volume for PG data
Why single‑container? Contest rules ask for an "all‑in‑one" image. In production you'd usually separate the database, but this setup simplifies demos while retaining durability through EFS‑backed volumes.
appservice – same image used in Fargate, exposing ports 3000 (web) & 5432 (db).- Volume mounts keep chat data and node_modules between runs.
docker‑compose up --buildhackloumi-chat/
├── src/ # All application code (frontend & backend)
│ ├── components/
│ ├── pages/
│ ├── lib/
│ └── ...
├── deploy/ # Infrastructure‑as‑Code (AWS CDK / Terraform)
│ └── ...
├── scripts/ # Helper CLI & test utilities
│ └── perf-test.sh
└── README.md # You are here
-
Prerequisites
- Docker & Docker Compose
- Node ≥ 18 (if you want to run outside containers)
-
Clone & Run Locally
git clone https://github.com/your-org/hackloumi-chat.git
cd hackloumi-chat
docker‑compose up --build- Open
http://localhost:3000in your browser, create an account, add a friend, and start chatting 😊
Each milestone is released as its own pull request and Git tag. Tick the boxes to track progress.
-
npx create-next-app@latestwith workspace layout and TS config - ESLint, Prettier, and Husky pre‑commit hooks
- Vitest set up with a sample test
- GitHub Actions workflow: lint + test
- User registration form (username + password ×2)
- Password hashed with Argon2, stored in PostgreSQL
- JWT auth cookie issued on login
-
/chat/[user]page with textarea & send button - POST
/api/messagespersists message - GET
/api/messages?peer=long‑polls for new messages
- Invite by username
- Accept / reject invitation workflow
- Contacts shown in sidebar sorted alphabetically
- Prisma migration adds
ftscolumn (PostgreSQL tsvector) - GET
/api/search?q=returns ranked matches from both direct and group messages - Search bar on top of chat list with instant results and navigation to both direct/group chats
- Upgrade long‑poll to WebSocket handshake
- In‑memory queue delivers message to connected peers
- Delivery ACK updates message status to delivered
- Fallback to polling when WebSocket unsupported
-
groupstable (id,name,owner_id) - Endpoints to create, rename, and delete rooms
- Add / remove participants with owner approval
- Broadcast fan‑out to all members over WebSocket
- Local file upload with
/api/uploadendpoint for image storage - Markdown parsing for bold / italic /
codein both direct and group messages -
<LazyImage>component with lazy‑loading and loading states for message images - Image support in both direct messages and group chats with real-time delivery
- Route
/u/[username]focuses a DM - Route
/g/[id]opens group chat (auto‑join if invited) - Graceful 404 page when target not found
- Hover a message → add emoji reaction (👍 😂 ❤️ etc.)
- Display reaction counters aggregated per emoji
-
/profile/[username]sheet shows avatar, bio, shared groups
- Locust script simulates 1 000 users at 50 msg s⁻¹
- Collect metrics via
pg_stat_statements+ Node cluster stats - Grafana dashboard with CPU, memory, p99 latency
- Dockerfile multi‑stage: build → runtime (Node 18‑slim + PostgreSQL 16‑alpine via supervisord)
-
docker‑compose.ymlexposes 3000 & 5432 volumes - Terraform provisions: VPC, ALB, Fargate task, EFS, S3 bucket, IAM roles
- Makefile with
make deploy&make destroywrappers - Readiness & liveness probes for health checks
Pull requests are welcome — whether they fix a typo, craft a new feature, or push the performance envelope.
File issues on GitHub or start a discussion if you have ideas!
MIT — free to use, modify, and distribute.
Made with ♥ and a shoestring budget.