SAHIM API

SAHIM API is the backend service that powers the SAHIM platform.

• Prerequisites
• Getting Started
• Start Development Server
• Accessing the Database
  • 5. Exit the Database Session
• API Documentation
  • Runtime Documentation
  • Static Documentation
• Troubleshooting
  • 1. Database Connection Issues
• Contributors
  • API
  • Web Client

---

Prerequisites

• Node.js (v20 or higher)
• pnpm (v10 or higher)
• Docker

---

Getting Started

Follow these steps to set up your development environment:

1. Install Dependencies

   pnpm i

2. Set Up Docker Environment

   docker compose up

   This will set up necessary services like the database.

3. Configure Environment Variables

   • Copy the example environment file:

     cp .env.example .env

   • Open .env and update the variables according to your setup

4. Initialize Database

   pnpm prisma migrate dev

   This command will:

   • Create the database if it doesn't exist
   • Apply all pending migrations
   • Generate the Prisma Client

5. Ensure the CHECK Constraint is Applied

   Prisma does not support CHECK constraints, so follow this step to manually enforce it:

   • First, access the database (see Accessing the Database).
   • Then run the following SQL command (Use shift+insert or ctrl+shift-v to paste):

   ALTER TABLE "Student"
   ADD CONSTRAINT study_level_check CHECK ("studyLevel" >= 1 AND "studyLevel" <= 5);

   This ensures that studyLevel is always between 1 and 5.

   ✅ To verify the constraint is applied, run:

   \d+ "Student"

   You should see:

   Check constraints:
      "study_level_check" CHECK ("studyLevel" >= 1 AND "studyLevel" <= 5)
   

6. Initialize Storage

   pnpm init:storage

   This will:

   • Create a storage directory in the root with its sub directories and files.
   • Generate JWT keys into keys/ for authentication

7. Start Development Server

   pnpm start:dev

   The API will be available at http://localhost:5000 by default.

---

Start Development Server

If you've already set up the development environment (as mentioned in Getting Started section), follow these steps to run the development server:

1. Start the PostgreSQL database:

   docker compose up -d

2. Apply any pending database migrations:

   pnpm prisma migrate dev

3. Start the server in development mode:

   pnpm start:dev

4. Access the API:

   • Default: http://localhost:5000
   • Custom: Use the PORT specified in your .env file

---

Accessing the Database

If you need to connect to the PostgreSQL database running inside Docker, follow these steps:

1. Identify the Running Database Container First, list all running Docker containers to find the database container ID:

docker ps

This will display a list of running containers. Look for the CONTAINER ID associated with your PostgreSQL instance.

2. Connect to the Database Once you have the correct CONTAINER ID, use it in the following command to enter the PostgreSQL interactive shell:

docker exec -it <container_id> psql -U postgres -d sahim

Replace <container_id> with the actual ID from Step 1.

3. Verify Connection After running the above command, you should see the PostgreSQL prompt:

sahim=#

From here, you can run SQL commands to interact with your database.

Tip: sse Shift + Insert or Ctrl + Shift + V to paste commands in the terminal.

4. List Available Tables (Optional) To check if your database has been set up correctly, run:

\dt

This will display all tables in the current schema.

5. Exit the Database Session

When you're done, type:

\q

or press Ctrl + D to exit.

---

API Documentation

SAHIM API provides two ways to access the Swagger documentation:

Runtime Documentation

When running the development server, you can access the interactive Swagger UI at:

http://localhost:5000/docs

Replace 5000 with your PORT.

This provides real-time documentation of all available API endpoints, request/response schemas, and authentication requirements.

Static Documentation

For offline access or sharing with team members, you can generate static documentation:

1. Generate the static documentation files:

   pnpm generate:docs

2. The documentation will be generated in the docs/__GENERATED__/ directory:

   • swagger.json - OpenAPI specification in JSON format (git ignored)
   • swagger.yaml - OpenAPI specification in YAML format (git ignored)
   • index.html - Interactive documentation viewer

3. Open docs/__GENERATED__/index.html in your browser to view the static documentation.

Note: The static documentation is manually generated but does not require the server to be running.

---

Troubleshooting

1. Database Connection Issues

If you encounter database connection problems:

• Verify Docker containers are running: docker compose ps
• Check for conflicting PostgreSQL instances on the same port
• Ensure .env credentials match docker-compose.yml

Note: Always configure your .env file correctly before server startup.

Important: The database uses port 5433 to prevent conflicts. Verify your DATABASE_URL in .env:

DATABASE_URL="postgresql://postgres:postgres@localhost:5433/sahim?schema=public"

---

Contributors

This project is developed by a team of undergraduate students at the Department of Information Technology, Faculty of Engineering and Information Technology, Taiz University.

SAHIM (Student Academic Hub for Integrated Management) is a comprehensive academic platform built as part of our final Software Engineering course (L3), applying software development principles, team collaboration practices, and agile methodology.

API

-> View Repository

Web Client

-> View Repository