Internal Portal

One of my biggest projects that I built for the Saudi Government during my current employment, I lead this project as the main developer managing a team of 6 developers, assigning tasks, building templates, reviewing code, deployment, alignment with product teams and stakeholders.

An internal organizational tool built with Next.js that provides employees with centralized access to HR services, information management, and request processing systems. This portal streamlines internal workflows and serves as a central hub for employee self-service functions.

---

A comprehensive internal portal that provides employees with centralized access to organizational services, information management, and request processing systems.

🚀 Features

• Personalized Dashboard - Customizable widgets for quick access to information and actions
• News & Announcements - Company news, family updates, and internal advertisements
• Profile Management - Personal and employment information management
• Request System - Submit and track various requests (vacations, HR letters, medical claims)
• Employee Directory - Search colleagues and view department structures
• Form Management - Unified form submission system with validation
• Multi-language Support - Arabic and English interfaces

🛠️ Tech Stack

• Frontend: Next.js 15 (App Router), React 19, TypeScript
• Styling: Tailwind CSS, Radix UI Components
• State Management: Jotai
• Forms: React Hook Form with Zod validation
• Database: File-based storage (db.json)
• Testing: Vitest, React Testing Library
• Development: Storybook, ESLint, Prettier
• Deployment: Docker support

📚 Documentation

Quick Start

• Development Setup - Complete setup instructions
• Project Tour - Guided walkthrough

Architecture & Development

• Architecture Overview - Technical architecture details
• Features Guide - In-depth feature documentation
• UI & State Management - Component and state patterns
• Project Map - Feature-to-file mapping

Specialized Guides

• Form Submission Guide - Unified form submission logic
• Migration Guide - Form migration guidelines
• Testing Guide - Running and writing tests
• API Documentation - API schemas and endpoints

🚀 Quick Start

Prerequisites

• Node.js 18+ (20+ recommended)
• pnpm 9+ (package manager)
• Git for version control

Installation

1. Clone the repository

   git clone <repository-url>
   cd Internal-Portal

2. Install dependencies

   pnpm install

3. Environment Setup

   cp .env.example .env.local
   # Edit .env.local with your configuration

4. Initialize the database

   # Ensure the database file exists
   mkdir -p app/db
   # Copy default database if needed
   cp app/db/db.json.example app/db/db.json

Development

Start the development server:

pnpm dev

The application will be available at http://localhost:3000

Development with debugging:

pnpm dev:debug

Run Storybook for component development:

pnpm storybook

Storybook will be available at http://localhost:6006

Building for Production

Build the application:

pnpm build

Start the production server:

pnpm serve
# or
node .next/standalone/server.js

Using Next.js server (alternative):

pnpm start

⚠️ Note: This method may produce unexpected results. See Next.js Documentation for details.

🧪 Testing & Quality

Run tests:

pnpm test           # Run all tests
pnpm test:watch     # Run tests in watch mode
pnpm test:coverage  # Run tests with coverage

Linting and formatting:

pnpm lint           # Run ESLint
pnpm format         # Format code with Prettier

🐳 Docker Deployment

Build Docker image:

docker build -t internal-portal:latest .

Run Docker container:

docker run -it -p 3000:3000 internal-portal:latest

The application will be available at http://localhost:3000

🔧 Configuration

Environment Variables

Create a .env.local file in the root directory:

# Database Configuration
DATABASE_PATH=./app/db/db.json

# Authentication (if applicable)
AUTH_SECRET=your-auth-secret
AUTH_URL=http://localhost:3000

# External API URLs (customize as needed)
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api

# Feature Flags
NEXT_PUBLIC_ENABLE_FEATURE_X=true

Database Setup

The application uses a file-based database stored in app/db/db.json. For production deployments, ensure:

1. The database directory is writable
2. Regular backups are configured
3. Proper file permissions are set

🛠️ Troubleshooting

Common Issues

Node/pnpm version conflicts:

node --version  # Should be 18+
pnpm --version  # Should be 9+

Build failures:

# Clean install
pnpm reset  # This runs: rm -rf .next && rm -rf node_modules && pnpm i

Database issues:

# Reset database to default state
cp app/db/db.json.example app/db/db.json

Port conflicts:

# Check if port 3000 is in use
lsof -i :3000
# Kill process if needed
kill -9 <PID>

Complete Reset Procedure

If you encounter unexpected errors, run this complete reset:

# Clean all generated files
rm -rf .next
rm -rf node_modules  
rm -rf pnpm-lock.yaml

# Reinstall dependencies
pnpm install

# Rebuild the application
pnpm build

# Copy required files for standalone mode
cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
mkdir -p .next/standalone/app/db
cp app/db/db.json .next/standalone/app/db/

# Start the server
node .next/standalone/server.js

Debug Mode

For debugging issues:

# Enable debug output
NODE_OPTIONS='--inspect' pnpm dev

# For server debugging
pnpm dev-debug-server