Technical Overview

This document provides a comprehensive overview of UniLost’s architecture, core components, and underlying technologies.

Architecture

UniLost follows a client-server architecture with the following components:

  • Frontend: Single-page application (SPA) using HTML, JavaScript, and Tailwind CSS

  • Backend: Node.js server with Express.js framework

  • Database: PostgreSQL (production) or SQLite (development)

  • Real-time Communication: Socket.IO for WebSocket connections

System Architecture Diagram

┌─────────────┐
│   Client    │
│  (Browser)  │
│             │
│  Leaflet.js │
└──────┬──────┘
       │
       ├─────────────────────────┐
       │                         │
       │ HTTP/WebSocket          │ Direct HTTP Requests
       │                         │ (Map Tiles, Geocoding)
       │                         │
┌──────▼──────────────────┐     │
│   Express Server        │     │
│   (server.js)           │     │
│                         │     │
│  ┌──────────────────┐   │     │
│  │  REST API        │   │     │
│  │  /api/*          │   │     │
│  └──────────────────┘   │     │
│                         │     │
│  ┌──────────────────┐   │     │
│  │  Socket.IO       │   │     │
│  │  Real-time Chat  │   │     │
│  └──────────────────┘   │     │
└──────┬──────────────────┘     │
       │                         │
       │ Database Queries        │
       │                         │
┌──────▼──────────────┐          │
│   Database Module   │          │
│   (db.js)           │          │
└──────┬──────────────┘          │
       │                         │
┌──────▼──────────────┐          │
│  PostgreSQL/SQLite  │          │
└─────────────────────┘          │
                                 │
                       ┌─────────▼──────────────┐
                       │  External Services     │
                       │                        │
                       │  OpenStreetMap         │
                       │  - Tile Server         │
                       │  - Nominatim API       │
                       └────────────────────────┘

Core Components

Server (server.js)

The main server file handles:

  • HTTP Server: Express.js application serving static files and API endpoints

  • Session Management: Express-session middleware for user authentication

  • REST API: Endpoints for authentication, item management, and data retrieval

  • Socket.IO Server: Real-time communication for chat and item threads

  • Error Handling: Structured error handling system with custom error classes and environment-aware logging

Database Module (db.js)

The database module provides:

  • Connection Management: Handles both PostgreSQL and SQLite connections

  • Database Abstraction: Unified interface for database operations

  • Table Initialization: Automatic schema creation and default data

  • Query Functions: CRUD operations for users, items, chat, and threads

  • Error Handling: Comprehensive error handling with proper error types and logging

Error Handling Module (utils/errorHandler.js)

The error handling module provides:

  • Custom Error Classes: DatabaseError, ValidationError, AuthenticationError, AuthorizationError, NotFoundError

  • Structured Logging: Environment-aware logging (detailed in development, structured in production)

  • Error Normalization: Automatic conversion of unknown errors to appropriate error types

  • HTTP Response Handling: Proper status codes and safe error messages for clients

Frontend (unilost.html)

The frontend includes:

  • Map Integration: Leaflet.js for interactive maps

  • UI Components: Modal dialogs, forms, and navigation

  • Real-time Updates: Socket.IO client for live chat

  • API Client: Fetch API for REST endpoint communication

  • Responsive Design: Tailwind CSS for mobile and desktop layouts

Database Schema

Users Table

CREATE TABLE users (
    id VARCHAR(255) PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    pw_hash VARCHAR(255) NOT NULL,
    is_admin BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Items Table

CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    title VARCHAR(500) NOT NULL,
    description TEXT,
    category VARCHAR(100),
    img_data TEXT,
    lat DOUBLE PRECISION NOT NULL,
    lng DOUBLE PRECISION NOT NULL,
    radius DOUBLE PRECISION DEFAULT 0,
    status VARCHAR(50) DEFAULT 'pending',
    storage_place VARCHAR(255),
    created_by VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (created_by) REFERENCES users(id)
);

Chat Messages Table

CREATE TABLE chat_messages (
    id SERIAL PRIMARY KEY,
    nick VARCHAR(100) NOT NULL,
    text TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Thread Messages Table

CREATE TABLE thread_messages (
    id SERIAL PRIMARY KEY,
    item_id INTEGER NOT NULL,
    nick VARCHAR(100) NOT NULL,
    text TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE
);

Technologies Used

Backend Technologies

  • Node.js: JavaScript runtime environment

  • Express.js: Web application framework

  • Express-session: Session management middleware

  • bcrypt: Password hashing library

  • Socket.IO: Real-time bidirectional communication

  • pg: PostgreSQL client for Node.js

  • better-sqlite3: SQLite database driver

Frontend Technologies

  • HTML5: Markup language

  • JavaScript (ES6+): Programming language

  • Tailwind CSS: Utility-first CSS framework

  • Leaflet.js: Interactive map library

  • OpenStreetMap: Map tile provider

  • Socket.IO Client: Real-time communication client

Database Technologies

  • PostgreSQL: Production database

  • SQLite: Development database (file-based)

Security Features

  • Password Hashing: bcrypt with salt rounds

  • Session Security: HttpOnly cookies, SameSite protection

  • Input Validation: Server-side validation for all inputs

  • SQL Injection Prevention: Parameterized queries

  • XSS Protection: Input sanitization and output encoding

Data Flow

Item Registration Flow

  1. User fills out registration form

  2. Frontend sends POST request to /api/items

  3. Server validates input and checks authentication

  4. Database module creates new item record

  5. Server returns created item data

  6. Frontend updates map with new item marker

Real-time Chat Flow

  1. Client connects via Socket.IO

  2. Client emits chat:join event

  3. Server loads chat history from database

  4. Server emits chat:history to client

  5. When user sends message, client emits chat:send

  6. Server saves message to database

  7. Server broadcasts chat:new to all connected clients

Performance Considerations

  • Database Indexing: Indexes on frequently queried columns

  • Connection Pooling: PostgreSQL connection pool management

  • Caching: Session data caching

  • Lazy Loading: Map markers loaded on demand

  • Pagination: Chat history limited to recent messages

Scalability

  • Horizontal Scaling: Stateless server design allows multiple instances

  • Database Scaling: PostgreSQL supports replication and sharding

  • Load Balancing: Compatible with reverse proxies (nginx, etc.)

  • CDN Integration: Static assets can be served from CDN

For API details, see API Reference. For configuration options, see Configuration Guide.