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
• 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
npm 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
npm run swagger

# Build the project
npm run build

# Run tests to verify everything works
npm run 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)
npm run init:schema

# OR for MariaDB/MySQL
npm run 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
npm run 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
npm run build	Compile TypeScript to JavaScript
npm run watch	Start development server with hot reload
npm run test	Run all tests
npm run test-ci	Run tests with schema setup
npm run test-ci-migrate	Run tests with migration setup
npm run coverage	Generate test coverage report
npm run lint	Run ESLint
npm run lint-fix	Fix ESLint issues automatically
npm run schema	Create/update database schema (SQLite)
npm run migrate	Run database migrations (MariaDB/MySQL)
npm run seed	Seed database with initial data
npm run init:schema	Complete setup for SQLite development
npm run init:migrate	Complete setup for MariaDB/MySQL development
npm run maintenance	Run maintenance tasks
npm run cron	Start cron job scheduler
npm run 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: npm run test, or npm run test-file <path-to-test-file> to run a single test file
5. Run linting: npm run 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