2025-07-28 14:49:18 +05:30

11 KiB

Raw Blame History

SpurrinAI Backend

Welcome to the SpurrinAI Backend! This guide is designed for beginners and experienced developers alike. If you’re new to backend development, APIs, or deploying web services, don’t worry—this README will walk you through everything step by step.

What is SpurrinAI Backend?

SpurrinAI Backend is the server-side part of the SpurrinAI platform. It’s built with Node.js (JavaScript) and also uses a Python service for advanced features like PDF processing and AI-powered Q&A. This backend provides:

Secure user authentication and management for hospitals, admins, and app users
Document upload and processing (including PDFs)
Real-time chat and Q&A (using WebSockets)
Analytics and feedback collection
Integration with a Python AI service for smart answers

Who is this for?

Developers who want to run, test, or contribute to SpurrinAI

What is SpurrinAI Backend?
Key Concepts & Terms
Project Structure
Step-by-Step Setup
- Node.js Backend
- Python Service (for AI/PDF)
How to Run Everything
API Overview (What Can You Do?)
Authentication & Roles (How Login Works)
Controllers, Services, and Middleware (What’s Happening Inside?)
WebSocket Features (Real-Time Chat)
Database Migrations (Updating the Database)
Troubleshooting & Tips
Learn More
Support
License

Key Concepts & Terms

Backend: The part of an app that runs on a server, handles data, and talks to databases and other services. Users don’t see it directly.
API (Application Programming Interface): A way for different programs (like your frontend and backend) to talk to each other using HTTP requests (like GET, POST, etc.).
Node.js: A popular way to run JavaScript on the server (not just in the browser).
Python: Another programming language, used here for AI and PDF features.
PM2: A tool that keeps your server running, restarts it if it crashes, and makes it easy to manage multiple services (Node.js and Python).
JWT (JSON Web Token): A secure way to prove who you are (used for login/authentication).
WebSocket: A technology for real-time, two-way communication (like chat) between your browser and the server.
.env file: A file where you put secret settings (like passwords and API keys) so you don’t hard-code them in your code.

Project Structure

Here’s what the main folders and files do:

project-root/
├── src/                    # All the main code
│   ├── app.js              # Where the app starts
│   ├── config/             # Settings and configuration
│   ├── controllers/        # Code that handles each API request
│   ├── middleware/         # Code that runs before/after requests (security, auth, etc.)
│   ├── migrations/         # Database update scripts
│   ├── routes/             # Defines all the API endpoints
│   ├── services/           # Business logic and helpers
│   └── utils/              # Utility functions
├── docs/                   # Extra documentation
├── logs/                   # Where logs are saved
├── scripts/                # Helper scripts
├── tests/                  # Automated tests
└── uploads/                # Where uploaded files go (PDFs, images)

Step-by-Step Setup

Node.js Backend

Install Node.js and npm
- Download from nodejs.org
- Check with:
```
node -v
npm -v
```
- You need Node.js 14+ and npm 6+

Clone the repository

git clone <repo_url>
cd spurrinai-backend

Install Node.js dependencies
```
npm install
```
- This downloads all the code libraries the backend needs.

Set up your environment variables

cp .env.example .env
# Open .env in a text editor and fill in your settings (DB password, etc.)

Never share your .env file publicly!

Run the setup script
```
npm run setup
```
- This may create database tables or do other first-time setup.

Python Service (for AI/PDF)

Some features (like PDF processing and AI Q&A) need a separate Python service. Here’s how to set it up:

Install Python 3
- Download from python.org
- Check with:
```
python3 --version
```
Create a virtual environment (keeps dependencies isolated)
```
python3 -m venv venv
```
Activate the virtual environment
- On Linux/macOS:
```
source venv/bin/activate
```
- On Windows:
```
venv\Scripts\activate
```
Install Python dependencies
```
pip install -r requirements.txt
```

How to Run Everything

Using PM2 (Recommended for Beginners)

PM2 is a process manager. It keeps your backend and Python service running, restarts them if they crash, and makes it easy to start/stop everything with simple commands.

Install PM2 globally
```
npm install -g pm2
```

Start the Node.js backend

pm2 start src/app.js --name spurrinai-backend

Start the Python service
```
pm2 start chat.py --interpreter venv/bin/python --name=python-file
```
- This tells PM2 to use your Python virtual environment.
Check everything is running
```
pm2 list
pm2 logs
```

Other useful PM2 commands

pm2 restart <name>
pm2 stop <name>
pm2 delete <name>
pm2 monit

Tip: If you ever reboot your server, you can run pm2 resurrect to bring everything back up, or use pm2 startup to make PM2 start on boot.

API Overview (What Can You Do?)

This backend provides many features. Here’s a simple summary of what each group of API endpoints does:

Login: /api/auth/login — Log in as an admin or hospital user. You’ll get a token to use for other requests.

Super Admins

Manage the highest-level users (can create hospitals, manage other admins, etc.)

Hospitals

Create, update, and manage hospitals and their settings.
Upload hospital logos, manage users, and more.

Users (Hospital/Admin)

Add, edit, or remove users from a hospital.
Manage user profiles and passwords.

App Users

Register and log in as an app user (patients, clients, etc.).
Upload ID photos, manage chat sessions, and more.

Documents

Upload and manage documents (PDFs, images) for hospitals and users.

PDF Processing

Send PDFs to the Python service for processing and Q&A extraction.

Feedback

Submit and view feedback between users, hospitals, and admins.

Analytics

Get reports and statistics about hospitals and users.

Excel Data

Upload and process Excel files (admin only).

Onboarding

Track and fetch onboarding steps for users.

Roles

List all available user roles.

For a full list of endpoints and what they do, see the API Overview section above.

JWT-based authentication: When you log in, you get a special token (JWT) that proves who you are. You must include this token in the Authorization header for most requests:
```
Authorization: Bearer <your-token-here>
```
Roles: Different users have different permissions:
- Spurrinadmin: Top-level admin
- Superadmin: Hospital owner/admin
- Admin: Hospital staff
- Viewer: Read-only user
- AppUser: Regular app user (patient, etc.)
The backend checks your role before letting you do certain things.

Controllers, Services, and Middleware (What’s Happening Inside?)

Controllers: The main logic for each API endpoint (e.g., login, upload document, etc.)
Services: Helper code for things like talking to the database, generating tokens, or calling the Python AI service.
Middleware: Code that runs before/after your request (checks your token, rate-limits requests, adds security headers, etc.)

You don’t need to change these to use the API, but if you want to contribute or learn, check out the src/controllers/, src/services/, and src/middleware/ folders.

WebSocket Features (Real-Time Chat)

WebSocket lets you have live, two-way chat between the app and the backend (for Q&A, chatbots, etc.).
The backend runs a WebSocket server on port 40510 (and a secure one on 40520).
You need to send your JWT token when connecting.
Used for real-time Q&A and chat sessions.

Database Migrations (Updating the Database)

If you change the database structure (add tables, etc.), you’ll use migrations. Here’s how:

Create a new migration:
```
npm run migrate:create
```
Run all migrations:
```
npm run migrate
```
Run migrations up:
```
npm run migrate:up
```
Run migrations down:
```
npm run migrate:down
```

Troubleshooting & Tips

Port already in use?
- You might already have something running on the same port. Stop it or change the port in your .env file.
Missing dependencies?
- Run npm install (Node.js) or pip install -r requirements.txt (Python) again.
.env file errors?
- Make sure you copied .env.example to .env and filled in all the required values.
Database connection issues?
- Check your DB settings in .env. Make sure MySQL is running and accessible.
Python service not working?
- Make sure you activated your virtual environment and installed all dependencies.
- Check PM2 logs with pm2 logs python-file.
Need to reset everything?
- You can stop all PM2 processes with pm2 delete all and start again.

11 KiB Raw Blame History Unescape Escape