> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/praveenarya123/sps-backend/llms.txt
> Use this file to discover all available pages before exploring further.

# Server setup

> Install and run the SPS School Backend locally or with MongoDB Atlas.

This guide walks you through setting up the SPS School Backend on your machine for local development or connecting it to a hosted MongoDB Atlas cluster.

## Prerequisites

Before you begin, make sure the following are installed:

| Requirement | Minimum version      | Notes                   |
| ----------- | -------------------- | ----------------------- |
| Node.js     | 18.x                 | LTS recommended         |
| npm         | 9.x                  | Bundled with Node.js    |
| MongoDB     | 6.x (local) or Atlas | See setup options below |

<Tip>
  Check your installed versions with `node -v`, `npm -v`, and `mongod --version` before continuing.
</Tip>

## Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/praveenarya123/sps-backend.git
    cd sps-backend
    ```
  </Step>

  <Step title="Install dependencies">
    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn install
        ```
      </Tab>
    </Tabs>

    This installs all production and development dependencies defined in `package.json`, including Express, Mongoose, bcryptjs, jsonwebtoken, and nodemon.
  </Step>

  <Step title="Configure environment variables">
    Copy the example environment file and fill in your values:

    ```bash theme={null}
    cp .env.example .env
    ```

    At minimum, set `PORT`, `MONGODB_URI`, and `JWT_SECRET`. See the [environment variables reference](/guides/environment) for details on each variable.
  </Step>

  <Step title="Set up MongoDB">
    Choose your database setup:

    <Tabs>
      <Tab title="Local MongoDB">
        Install [MongoDB Community Edition](https://www.mongodb.com/try/download/community) for your operating system.

        <CodeGroup>
          ```bash macOS (Homebrew) theme={null}
          brew tap mongodb/brew
          brew install mongodb-community
          brew services start mongodb-community
          ```

          ```bash Ubuntu / Debian theme={null}
          sudo apt-get install -y mongodb
          sudo systemctl start mongod
          sudo systemctl enable mongod
          ```

          ```bash Windows theme={null}
          # Download the MSI installer from mongodb.com/try/download/community
          # Run the installer and choose "Run MongoDB as a Service"
          ```
        </CodeGroup>

        Once MongoDB is running, set your connection string in `.env`:

        ```bash theme={null}
        MONGODB_URI=mongodb://localhost:27017/sps-school
        ```

        MongoDB will create the `sps-school` database automatically on first write.
      </Tab>

      <Tab title="MongoDB Atlas">
        1. Sign in to [MongoDB Atlas](https://cloud.mongodb.com).
        2. Create a new project and deploy a free M0 cluster.
        3. Under **Database Access**, add a database user with a strong password.
        4. Under **Network Access**, allow your IP address (or `0.0.0.0/0` for development).
        5. Click **Connect** on your cluster, choose **Drivers**, and copy the connection string.

        Paste it into your `.env` file, replacing the placeholder credentials:

        ```bash theme={null}
        MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.abcde.mongodb.net/sps-school?retryWrites=true&w=majority
        ```

        <Warning>
          Never commit your Atlas connection string to version control. It contains your database credentials.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start the server">
    <Tabs>
      <Tab title="Development (nodemon)">
        ```bash theme={null}
        npx nodemon server.js
        ```

        nodemon watches for file changes and automatically restarts the process. This is the recommended mode during active development.

        <Note>
          You can also add a `dev` script to `package.json` for convenience:

          ```json theme={null}
          "scripts": {
            "dev": "nodemon server.js",
            "start": "node server.js"
          }
          ```

          Then run `npm run dev`.
        </Note>
      </Tab>

      <Tab title="Production (node)">
        ```bash theme={null}
        node server.js
        ```

        In production, use a process manager such as [PM2](https://pm2.keymetrics.io/) to keep the server running and handle restarts:

        ```bash theme={null}
        npm install -g pm2
        pm2 start server.js --name sps-school-backend
        pm2 save
        pm2 startup
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Verify the server is running

Once the server starts, confirm it is responding correctly by sending a request to the root endpoint:

```bash theme={null}
curl http://localhost:5000/
```

Expected response:

```text theme={null}
SPS School Backend Running
```

You can also open `http://localhost:5000/` in your browser and you should see the same message.

<Info>
  The default port is `5000`, read from `process.env.PORT`. If you set a different value in your `.env` file, use that port instead.
</Info>

## Project structure

The following tree shows the top-level layout of the project:

```
sps-backend/
├── server.js              # Entry point
├── package.json
├── .env                   # Local config (do not commit)
├── config/
│   └── db.js              # MongoDB connection
├── routes/
│   ├── authRoutes.js
│   ├── teacherRoutes.js
│   ├── studentRoutes.js
│   ├── attendanceRoutes.js
│   ├── assignmentRoutes.js
│   ├── applicationRoutes.js
│   └── financeRoutes.js
├── controllers/
│   ├── authController.js
│   ├── studentController.js
│   ├── teacherController.js
│   ├── attendanceController.js
│   ├── assignmentController.js
│   ├── applicationController.js
│   └── financeController.js
├── middleware/
│   ├── authMiddleware.js
│   └── roleMiddleware.js
└── models/
    ├── User.js
    ├── Student.js
    ├── Teacher.js
    ├── Attendance.js
    ├── Assignment.js
    ├── Submission.js
    ├── Application.js
    └── Fee.js
```

| File / folder  | Purpose                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------- |
| `server.js`    | Application entry point. Initializes Express, mounts routes, and starts the HTTP server. |
| `config/db.js` | Establishes the Mongoose connection to MongoDB using `MONGODB_URI`.                      |
| `routes/`      | One file per resource. Each file defines the route handlers for that domain area.        |
| `controllers/` | Business logic separated from routing. Called by route handlers.                         |
| `middleware/`  | Reusable middleware, including JWT authentication checks.                                |
| `models/`      | Mongoose schema and model definitions.                                                   |
| `.env`         | Local environment configuration. Never commit this file.                                 |

## Available API routes

The following base paths are mounted in `server.js`:

| Route prefix       | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `GET /`            | Health check — returns `"SPS School Backend Running"` |
| `/api/auth`        | Authentication (register, login)                      |
| `/api/teacher`     | Teacher management                                    |
| `/api/student`     | Student management                                    |
| `/api/attendance`  | Attendance tracking                                   |
| `/api/assignment`  | Assignment management                                 |
| `/api/application` | Applications and admissions                           |
| `/api/finance`     | Finance and fee management                            |

## Next steps

<CardGroup cols={2}>
  <Card title="Environment variables" icon="key" href="/guides/environment">
    Full reference for all required and optional environment variables.
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    How to authenticate requests using JWT tokens.
  </Card>
</CardGroup>