Kumpel Chat 💬

A modern, real-time chat application built with Next.js and Phoenix WebSocket.

For a maintainer-oriented overview (stack, env vars, API/WebSocket shape, deployment), see doc/project_analysis.md.

🚀 Features

• Real-time Messaging: Instant message delivery using WebSocket technology
• Room Management: Create and join chat rooms with unique codes
• User Authentication: Secure login and registration system
• Persistent Sessions: Access + refresh tokens in local storage; the client renews expired access tokens via the API’s refresh endpoint before retrying failed requests
• Modern UI: Clean, dark-themed interface with smooth animations
• Responsive Design: Works seamlessly on desktop and mobile devices
• User Colors: Each user gets a unique color for better message distinction
• Auto-scroll: Smart scrolling that respects user's reading position

Background tabs and auth (short)

• Mobile / background: Unread badges need JavaScript + WebSocket. If the browser suspends the tab (app switcher, another app in front), messages are not received until you open Kumpel again; the client then reconnects. For alerts while away you’d add Web Push (service worker + server) or fetch message history from the API after reconnect.
• Back vs logout: Auth uses router.replace('/dashboard') and auto-redirect from / and /login when a token exists, so the system back button does not strand you on login while still logged in. Logout still clears the session.

Details: doc/project_analysis.md → Background delivery, auth navigation, and long-lived sessions.

🛠️ Tech Stack

• Frontend:

  • Next.js 15 (App Router)
  • React
  • TypeScript
  • Tailwind CSS
  • shadcn/ui
  • Zustand (State Management)

• Backend:

  • Phoenix WebSocket
  • Elixir

📋 Prerequisites

• Bun (recommended: match packageManager in package.json, e.g. 1.2.x)
• Access to the Kumpel backend server

Bun bundles a JavaScript runtime compatible with Next.js; you do not need a separate Node install for local dev unless you prefer it.

🚀 Getting Started

1. Clone the repository

   git clone https://github.com/MarcosFlavioGS/Kumpel_client.git
   cd kumpel_app

2. Install dependencies

   bun install

   Commit bun.lock with the repo so CI and Vercel stay reproducible.

3. Environment Setup With bun run dev, the app defaults to the local API at http://localhost:4000 and WebSocket at ws://localhost:4000 (run the Phoenix backend with mix phx.server on port 4000).

   Important: the dev server speaks plain HTTP, not TLS. For localhost you must use http:// and ws://. Using https:// or wss:// against localhost:4000 makes the browser send TLS on a non-TLS port; the backend may log a warning like "Connection that looks like TLS received on a clear channel" and requests will fail.

   Optional: create a .env.local to override (e.g. point at production while developing the UI):

   NEXT_PUBLIC_API_URL=https://kumpel-back.fly.dev
   NEXT_PUBLIC_WS_URL=wss://kumpel-back.fly.dev

   For local backend explicitly (same as defaults):

   NEXT_PUBLIC_API_URL=http://localhost:4000
   NEXT_PUBLIC_WS_URL=ws://localhost:4000

4. Run the development server

   bun run dev

5. Open your browser Visit http://localhost:3000

☁️ Deploying on Vercel

Installs use Bun via vercel.json → bun install --frozen-lockfile (with bun.lock committed). Vercel detects Bun when a Bun lockfile is present. Set NEXT_PUBLIC_API_URL and NEXT_PUBLIC_WS_URL in the Vercel project to your production API if needed.

📁 Project Structure

kumpel_app/
├── src/
│   ├── app/                 # Next.js app directory
│   │   ├── stores/         # Zustand stores
│   │   ├── hooks/          # Custom hooks
│   │   └── ...            # App routes
│   ├── components/         # React components
│   │   ├── ui/            # shadcn/ui components
│   │   ├── chatRoom.tsx   # Chat room interface
│   │   └── ...           # Other components
│   └── type/              # TypeScript type definitions
├── doc/                   # Architecture notes (see project_analysis.md)
├── public/                # Static assets
└── ...                   # Configuration files

🔧 Key Components

• Chat Room: Real-time messaging interface with auto-scroll
• Dashboard: Room management and navigation
• Authentication: Secure login and registration
• State Management: Persistent user sessions with Zustand

🔐 Authentication Flow

1. User registers with email and password
2. Receives JWT token for authentication
3. Token is stored in localStorage for persistence
4. Protected routes check for valid token

🌐 API Endpoints

• POST /api/auth/login - User login
• POST /api/users - User registration
• POST /api/rooms - Create a room (body: { "name": "<name>" }; authenticated). The API assigns a random access code and returns it in the response.
• POST /api/rooms/subscribe - Join a chat room (body: { "name": "<room name>", "code": "<access code>" }; authenticated)
• GET /api/currentUser - Get user's rooms and data

User and room identifiers in API responses are UUID strings. WebSocket channel topics use chat_room:<room_uuid> with join payload { "code": "<access code>" }.

🎨 UI & UX

• Discord-inspired dark UI: blurple accent (#5865F2), layered greys (kumpel.* tokens in Tailwind), soft panel shadows, and glass-style auth cards (kumpel-auth-bg / kumpel-auth-panel in globals.css).
• Dashboard: channel sidebar with selection states, skeleton loading, empty-state guidance, accessible channel rows (buttons). On small screens, the list and chat stack: you get a full-width channel list, then full-width chat with a back control to return to the list (md and up keeps the split sidebar + chat).
• Chat: connection status per room, join-error banner, message bubbles, “jump to latest” when scrolled up. Per-room history and unread badges on the sidebar (multi-room WebSocket subscriptions + persisted kumpel-chat store).
• Shared form styling lives in src/lib/kumpel-ui.ts; full design notes are in doc/project_analysis.md (section UI & design system).

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Next.js
• Phoenix Framework
• shadcn/ui
• Zustand