Fidechat Backend

A modern real-time chat application backend built with NestJS, Oracle Database, and WebSocket integration. This project features guild-based chat rooms, user authentication via Keycloak, and a robust database architecture with Oracle PL/SQL packages.

Index

1. 🚀 Features
2. 🛠️ Tech Stack
3. 📋 Prerequisites
4. ⚡ Quick Start
   • 1. Clone the Repository
   • 2. Install Dependencies
   • 3. Environment Configuration
   • 4. Start the Services
   • 5. Initialize the Database
   • 6. Run the Application
5. 🗂️ Project Structure
6. 🌐 API Endpoints
   • Postman Collection
   • Authentication
   • Users
   • Guilds
   • Channels
   • WebSocket Events
7. 🗄️ Database Schema
8. 📜 Available Scripts
9. 🐳 Docker Configuration
   • Starting Services
10. 🔐 Authentication Setup (Keycloak)
11. 🛠️ Troubleshooting
    • Common Issues

🚀 Features

• Real-time Communication: WebSocket integration for instant messaging
• Guild-based Architecture: Discord-like guild and channel management
• Authentication: Keycloak integration for secure user authentication
• Oracle Database: Enterprise-grade database with PL/SQL packages and procedures
• RESTful API: Complete CRUD operations for users, guilds, and channels
• Type Safety: Full TypeScript implementation with strict typing
• Validation: Input validation using class-validator
• Docker Support: Complete containerization with Docker Compose
• Kubernetes Support: Minikube setup for local Kubernetes cluster deployment

🛠️ Tech Stack

• Backend Framework: NestJS with Fastify
• Database: Oracle 18c Express Edition
• Authentication: Keycloak with PostgreSQL
• Language: TypeScript
• WebSockets: Socket.IO
• Validation: class-validator, class-transformer
• Containerization: Docker & Docker Compose (+ Kubernetes setup)
• Package Manager: pnpm

📋 Prerequisites

Before running this project, make sure you have the following installed:

• Node.js >= 20.X.X
• npm >= 10.X.X (or pnpm recommended)
• Docker and Docker Compose
• Git

⚡ Quick Start

1. Clone the Repository

git clone <repository-url>
cd Fidechat-backend

2. Install Dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

3. Environment Configuration

Create a .env file in the root directory with the following variables:

# Application
NODE_ENV=development
API_PORT=3000

# Oracle Database
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_USER=system
ORACLE_PWD=your_oracle_password
ORACLE_SERVICE_NAME=XEPDB1

# PostgreSQL (for Keycloak)
PG_USER=keycloak
PG_PASSWORD=your_postgres_password
PG_NAME=keycloak
DB_PORT=5432

# Keycloak
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=your_keycloak_admin_password
KC_PORT=8081
KEYCLOAK_URL=http://localhost:8081
KEYCLOAK_REALM=your_realm
KEYCLOAK_CLIENT_ID=your_client_id
KEYCLOAK_CLIENT_SECRET=your_client_secret

# Keycloak Database
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=your_postgres_password
KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak

4. Start the Services

# Start all services (Oracle, PostgreSQL, Keycloak)
docker-compose -f local-docker-compose.yaml up -d

# Wait for services to be ready (especially Oracle DB initialization)
# This may take a few minutes on first run

5. Initialize the Database

The Oracle database will be automatically initialized with the schema and packages from /sql/init.sql when the container starts for the first time.

6. Run the Application

# Development mode with hot reload
pnpm run dev

# Or using npm
npm run dev

# Production mode
pnpm run start:prod

The application will be available at:

• API: http://localhost:3000
• Keycloak Admin: http://localhost:8081 (admin/your_keycloak_admin_password)

🗂️ Project Structure

.
├── scripts                   # Helper scripts for project setup and maintenance
├── sql                       # Database scripts
│   ├── init.sql              # Main initialization script
│   ├── pkg_*.sql             # PL/SQL packages
│   └── triggers.sql
├── src                       # Application source code
│   ├── common                # Shared utilities and services
│   │   ├── logger            # Custom logging implementation
│   │   │   ├── constants     # Logger constants
│   │   │   ├── interfaces    # Logger interfaces
│   │   │   └── utils         # Logger utilities
│   │   └── utils             # Environment validation
│   ├── config                # Configuration files
│   ├── database              # Database connection and types
│   │   └── oracle            # Oracle-specific implementations
│   │       ├── query-builder # Query builder for Oracle
│   │       └── types         # Oracle-specific types
│   ├── modules               # Feature modules
│   │   ├── auth              # Authentication (Keycloak)
│   │   │   └── keycloak
│   │   ├── channel
│   │   ├── dashboard    
│   │   ├── gateway
│   │   ├── guild
│   │   └── user              # User management
│   │       └── currentUser   # Current user utilities (like sync data client <- backend)
│   └── utils                 # Utility functions
└── types                     # Global TypeScript types

🌐 API Endpoints

Postman Collection

todo

Authentication

• Authentication is handled via Keycloak JWT tokens
• Include Authorization: Bearer <token> header in requests

Users

• GET /user/sync - Get current user sync data
• User CRUD operations are handled via PL/SQL packages

Guilds

• POST /guild - Create a new guild
• GET /guild/:id - Get guild by ID
• PUT /guild/:id - Update guild
• DELETE /guild/:id - Delete guild

Channels

• POST /channel - Create a new channel
• GET /channel/:id - Get channel by ID
• PUT /channel/:id - Update channel
• DELETE /channel/:id - Delete channel

WebSocket Events

• GUILD_CREATE - Guild creation events
• CHANNEL_CREATE - Channel creation events
• Real-time updates for all guild and channel operations

=�� Database Schema

The application uses Oracle Database with the following main entities:

• APP_USER: User information and profiles
• GUILD: Chat server/guild data
• CHANNEL: Text channels within guilds
• GUILD_USERS: Many-to-many relationship for guild membership

Key PL/SQL packages:

• PKG_USER: User management operations
• PKG_GUILD: Guild management operations
• pkg_sync_data: Data synchronization functions

📜 Available Scripts

# Development
pnpm run dev              # Start development server with hot reload
pnpm run start:debug      # Start with debug mode

# Building
pnpm run build            # Build the application
pnpm run start:prod       # Start production server

# Code Quality
pnpm run lint             # Run ESLint
pnpm run format           # Format code with Prettier

🐳 Docker Configuration

The project includes a complete Docker setup:

• Oracle 18c Express: Main application database
• PostgreSQL: Keycloak database
• Keycloak: Authentication and authorization server

Starting Services

# Start all services
docker-compose -f local-docker-compose.yaml up -d

# View logs
docker-compose -f local-docker-compose.yaml logs -f

🔐 Authentication Setup (Keycloak)

1. Access Keycloak Admin Console at http://localhost:8081
2. Login with admin credentials from your .env file
3. Create a new realm or configure the existing one
4. Create a client for the application
5. Update the .env file with the client credentials

🛠️ Troubleshooting

Common Issues

1. Oracle Connection Issues

   • Ensure Oracle container is fully started (may take 2-3 minutes)
   • Check Oracle credentials in .env file
   • Verify ORACLE_SERVICE_NAME is correct

2. Keycloak Authentication

   • Verify Keycloak is accessible at the configured URL
   • Check client configuration in Keycloak admin
   • Ensure JWT tokens are properly formatted

3. WebSocket Connection Issues

   • Check CORS configuration
   • Pray to Jesus if all else fails

📝 To-Do List

• Fix socket connection TTL: Currently, using Keycloak, there is no mechanism to disconnect clients with expired Keycloak tokens. Implement a solution to refresh tokens or disconnect clients when their tokens expire.
• Implement missing CRUD operations in sockets.