Introduction

​

Welcome to Platform API

​

Key Features

​

Architecture Overview

src/
├── app.ts              # Express app configuration
├── main.ts             # Server bootstrap
├── routes.ts           # Main route registry
├── common/             # Shared utilities
│   ├── errors/         # Error handling
│   ├── logger/         # Winston logger
│   ├── middlewares/    # Auth & validation
│   └── utils/          # Helpers (JWT, tokens, async)
├── config/             # Environment configuration
├── db/                 # Prisma client
└── modules/
    └── auth/           # Authentication module
        ├── controllers/
        ├── services/
        ├── schemas/
        └── routes/

​

Tech Stack

​

Core Framework

• Runtime: Node.js 18+ with TypeScript 5.9+
• Framework: Express.js 5.2 - Fast, minimalist web framework
• Language: TypeScript - Type-safe development

​

Database & ORM

• Database: PostgreSQL 16+ - Robust relational database
• ORM: Prisma 7.2 - Next-generation ORM with type safety
• Adapter: @prisma/adapter-pg - Native PostgreSQL adapter

​

Authentication & Security

• JWT: jsonwebtoken 9.0 - JSON Web Token implementation
• Hashing: bcryptjs 3.0 - Password hashing with bcrypt
• Security: helmet 8.1 - Secure Express apps with HTTP headers
• CORS: cors 2.8 - Cross-Origin Resource Sharing

​

Validation & Logging

• Validation: Zod 4.2 - TypeScript-first schema validation
• Logging: Winston 3.19 - Universal logging library
• HTTP Logging: Morgan 1.10 - HTTP request logger middleware

​

Development Tools

• Runtime: tsx 4.21 - TypeScript execution with hot reload
• Build: tsc-alias 1.8 - Path alias resolution for TypeScript

​

Database Schema

​

Core Entities

• Users: Global user accounts with email verification, password management, and activity tracking
• Companies: Tenant workspaces with status management, soft deletes, and metadata support
• Memberships: User-Company relationships with roles, hierarchy (supervisor chains), and contract information

​

RBAC System

• Roles: Company-scoped roles with customizable permissions and colors
• Permissions: Global permission catalog with scope (GLOBAL or COMPANY)
• RolePermission: Many-to-many relationship between roles and permissions
• MembershipRole: Assigns roles to company members
• UserGlobalPermission: Platform-level permissions for users

​

Authentication

• RefreshToken: Secure token storage with hashing, expiration, and revocation support

​

Invitation System

• CompanyInvite: Single-use invites for creating companies (admin-issued)
• CompanyMemberInvite: Invites for joining existing companies (member/admin-issued)

​

Additional Features

• CompanyRequest: User-initiated company creation requests (approval workflow)
• PermissionRequest: User-initiated permission requests (approval workflow)
• PlatformAdmin: Super admin designation
• Projects, TimeEntry, Client: Time tracking capabilities

​

API Endpoints

​

Authentication

• POST /api/auth/register - Register new user account
• POST /api/auth/login - Login with email and password
• POST /api/auth/refresh - Refresh access token using refresh token
• POST /api/auth/logout - Logout and revoke refresh token
• GET /api/auth/me - Get current user profile with permissions and companies

​

Health Check

• GET /health - Service health status

​

Security Features

​

Password Security

• Passwords are hashed using bcrypt with salt rounds of 10
• Minimum password length: 8 characters
• Maximum password length: 100 characters

​

Token Management

• Access Tokens: Short-lived JWT tokens (default: 15 minutes)
• Refresh Tokens: Long-lived tokens (default: 7 days) stored as hashed values
• Token Revocation: Refresh tokens can be revoked on logout
• Token Rotation: New refresh token issued on each refresh

​

Account Protection

• Global Disable: isDisabled flag blocks all user access
• Company-level Status: Membership status controls company access
• Email Verification: emailVerified flag tracks verification status
• Last Login Tracking: lastLoginAt tracks user activity

​

Environment Configuration

# PostgreSQL Database
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=your_database_name

# API Configuration
NODE_ENV=production
PORT=3000

# JWT Configuration (use long random strings)
JWT_SECRET=your_jwt_secret_min_32_chars
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_SECRET=your_refresh_secret_min_32_chars
REFRESH_TOKEN_EXPIRES_IN=7d

# Invite Expiry
COMPANY_INVITE_EXPIRY_HOURS=72
MEMBER_INVITE_EXPIRY_HOURS=168

​

Next Steps