SudoSOS Backend

A comprehensive Point of Sale and Financial Management System for Study Association GEWIS

🎯 Overview

SudoSOS Backend is a comprehensive Point of Sale (POS) and financial management system designed specifically for Study Association GEWIS. It provides a robust API for managing transactions, user accounts, products, payments, and financial operations within the association.

🔧 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 22+ - Download here
• pnpm - Installation guide (enabled via corepack enable on Node.js 16.13+)
• Git - Download here
• OpenSSL - Usually pre-installed on most systems
• Database (choose one):
  • SQLite (default for development) - No additional setup required
  • MariaDB/MySQL - For production environments
• SQLite Viewer (optional) - DB Browser for SQLite or DataGrip

🚀 Quick Start

1. Clone and Setup

# Clone the repository
git clone https://github.com/GEWIS/sudosos-backend.git
cd sudosos-backend

# Install dependencies
pnpm install

# Copy environment configuration
cp .env.example .env

2. Generate JWT Key

# Generate RSA private key for JWT authentication
openssl genrsa -out config/jwt.key 2048

Verify the key was created correctly:

# Should start with -----BEGIN RSA PRIVATE KEY-----
head -1 config/jwt.key

3. Build and Test

# Generate swagger specification
pnpm swagger

# Build the project
pnpm build

# Run tests to verify everything works
pnpm test

4. Initialize Database

[!WARNING] > IMPORTANT: Clear your database before initializing!

• For SQLite: Delete the local.sqlite file if it exists
• For MariaDB: Drop all tables in your database

Quick Start for Development:

# For SQLite (recommended for development)
pnpm init:schema

# OR for MariaDB/MySQL
pnpm init:migrate

This command will:

• Create the database schema
• Seed it with initial data
• Run maintenance tasks
• Set up default roles and permissions

5. Start Development Server

# Start the development server with hot reload
pnpm watch

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

6. Access API Documentation

Visit http://localhost:3000/api-docs to access the Swagger UI for API documentation.

7. Get Authentication Token

1. Use the /authentication/mock endpoint with a valid userId to get a JWT token
2. In Swagger UI, simply enter the JWT token returned by the /authentication/mock endpoint
3. Use this token to authenticate API requests

8. Stripe Configuration (Optional)

For deposit functionality, configure Stripe with restricted keys only:

Required Environment Variables:

• STRIPE_PUBLIC_KEY - Your Stripe publishable key (safe for frontend)
• STRIPE_PRIVATE_KEY - Your Stripe restricted secret key (see permissions below)
• STRIPE_WEBHOOK_SECRET - Webhook endpoint secret for validation
• STRIPE_RETURN_URL - URL to redirect users after payment

Required Stripe Permissions: When creating your restricted API key, grant only these permissions:

• ✅ "Write access on all webhooks"
• ✅ "Write access on payment intents"

# Add these to your .env file
STRIPE_PUBLIC_KEY=pk_test_your_publishable_key_here
STRIPE_PRIVATE_KEY=sk_test_your_restricted_secret_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
STRIPE_RETURN_URL=https://your-domain.com/return

🛠️ Development Setup

Available Scripts

Script	Description
pnpm build	Compile TypeScript to JavaScript
pnpm watch	Start development server with hot reload
pnpm test	Run all tests
pnpm test-ci	Run tests with schema setup
pnpm test-ci-migrate	Run tests with migration setup
pnpm coverage	Generate test coverage report
pnpm lint	Run ESLint
pnpm lint-fix	Fix ESLint issues automatically
pnpm schema	Create/update database schema (SQLite)
pnpm migrate	Run database migrations (MariaDB/MySQL)
pnpm seed	Seed database with initial data
pnpm init:schema	Complete setup for SQLite development
pnpm init:migrate	Complete setup for MariaDB/MySQL development
pnpm maintenance	Run maintenance tasks
pnpm cron	Start cron job scheduler
pnpm serve	Start production server

📚 API Documentation

Swagger UI

• Development: http://localhost:3000/api-docs
• Production: https://sudosos.gewis.nl/api/api-docs/

Comprehensive Documentation

For detailed documentation, API references, and examples, visit the SudoSOS documentation site here:

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Run tests: pnpm test, or pnpm test-file <path-to-test-file> to run a single test file
5. Run linting: pnpm lint-fix
6. Commit your changes: git commit -m "feat: add your feature" (follow the conventional commits format)
7. Push to your branch: git push origin feature/your-feature-name
8. Create a Pull Request

IDE Setup (IntelliJ/WebStorm)

For easy ESLint integration:

1. Go to Preferences → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
2. Check "Run ESLint --fix on save"
3. Apply changes

📄 License

This project is licensed under the GNU Affero General Public License v3.0 or later. See the LICENSE file for details.

👥 Contributors

This project exists thanks to all the people who contribute code.

---

Made with ❤️ by Study Association GEWIS