{"id":29133073,"url":"https://github.com/gp-silah/silah-backend","last_synced_at":"2026-05-10T03:07:23.237Z","repository":{"id":301098586,"uuid":"1007710879","full_name":"GP-Silah/silah-backend","owner":"GP-Silah","description":"Powering Silah behind the scenes; secure auth, role control, cloud storage, and structured modular logic.","archived":false,"fork":false,"pushed_at":"2025-06-25T06:34:35.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T06:34:48.668Z","etag":null,"topics":["b2b","backend","nestjs","postgresql","prisma","website"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GP-Silah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T12:13:27.000Z","updated_at":"2025-06-25T06:09:54.000Z","dependencies_parsed_at":"2025-06-25T06:46:47.338Z","dependency_job_id":null,"html_url":"https://github.com/GP-Silah/silah-backend","commit_stats":null,"previous_names":["gp-silah/silah-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GP-Silah/silah-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GP-Silah%2Fsilah-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GP-Silah%2Fsilah-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GP-Silah%2Fsilah-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GP-Silah%2Fsilah-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GP-Silah","download_url":"https://codeload.github.com/GP-Silah/silah-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GP-Silah%2Fsilah-backend/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262727708,"owners_count":23354665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["b2b","backend","nestjs","postgresql","prisma","website"],"created_at":"2025-06-30T07:01:56.804Z","updated_at":"2026-05-10T03:07:23.229Z","avatar_url":"https://github.com/GP-Silah.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Silah Backend\n\n_Last Updated: January 2026_\n\nThis is the backend API server for [Silah](https://github.com/GP-Silah), an AI-augmented full-stack B2B platform that connects suppliers and buyers. Built using [NestJS](https://nestjs.com/), a progressive Node.js framework for building efficient and scalable server-side applications.\n\n- 📘 [Compodoc Documentation](https://gp-silah.github.io/silah-backend)\n- 📙 [Swagger API Reference](https://gp-silah.github.io/silah-backend/swagger)\n\n\u003e **Silah** (Arabic: صِلَة) _[noun]_ Connection, bond, link; often used to describe the ties between people, family, or communities.\n\n---\n\n## Architecture Overview\n\nThis NestJS backend handles:\n\n- **User Management \u0026 Authentication** (with Commercial Registration verification)\n- **Product \u0026 Service Catalog Management**\n- **Order Processing \u0026 Management**\n- **Request for Proposals (RFP) System**\n- **Real-time Chat \u0026 Notifications**\n- **File Upload \u0026 Storage** (Cloudflare R2 integration)\n- **Payment Processing** (Tap Payments integration)\n- **Multi-language Support** (DeepL Translate API)\n\n\u003e **Note:** AI features (semantic search, demand forecasting) are handled by a separate FastAPI backend.\n\n---\n\n## Tech Stack\n\n- **Framework:** NestJS (Node.js)\n- **Database:** PostgreSQL with Prisma ORM\n- **Authentication:** JWT + Wathq API (Commercial Registration verification)\n- **Storage:** Cloudflare R2 (for file/image storage)\n- **Payments:** Tap Payments Gateway\n- **Translation:** DeepL Translate API\n- **Real-time:** WebSockets for chat and notifications\n- **Testing:** Jest (Unit, Integration, E2E)\n- **DevOps:** Docker \u0026 Docker Compose\n\n---\n\n## Prerequisites\n\nBefore you start, make sure you have:\n\n- Node.js \u003e= 20\n- npm \u003e= 10\n- Docker \u0026 Docker Compose \u003e= 2 (strongly recommended)\n- PostgreSQL \u003e= 16 (if not using Docker)\n\n---\n\n## Required API Keys \u0026 Accounts\n\nYou'll need accounts and API keys for:\n\n- SendGrid (sending emails)\n- Tap Payments (payment processing)\n- Cloudflare R2 (file storage)\n- Wathq API (Saudi Commercial Registration verification)\n- DeepL Translate API (for auto-translation of products and services data)\n\n---\n\n## Getting Started\n\n### Method 1: With Docker (Recommended)\n\nDocker simplifies setup by handling the database and environment automatically.\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/GP-Silah/silah-backend.git\ncd silah-backend\n```\n\n#### 2. Install Dependencies\n\n```bash\nnpm install\n```\n\n#### 3. Set Up Environment Files\n\nCreate your environment configuration files:\n\n```bash\n# Copy the example files\ncp .env.example .env\ncp .env.dev.example .env.dev\ncp .env.test.example .env.test\n```\n\n**Understanding the Environment Files:**\n\n- `.env` used for shared variables (database credentials, API keys)\n- `.env.dev` used for development database connection\n- `.env.test` used for test database connection (separate from dev)\n\n**Why seperate database config?** Prisma only accepts one `DATABASE_URL` at a time, but we need different databases for development and testing. Our setup dynamically switches between them.\n\n#### 4. Configure Your Environment Variables\n\nEdit the `.env` files with your actual values.\n\n#### 5. Start the Development Environment\n\n```bash\nnpm run docker:dev\n```\n\nThis single command will:\n\n- Start PostgreSQL database on port 5432\n- Start NestJS backend on port 3000 with hot reload\n- Run database migrations automatically\n- Seed the database with categories\n- Set up health checks to ensure everything is connected\n\n**Important:** The category seeding step is crucial. It inserts ~50 predefined categories that the application relies on. Skipping this will break category-related features.\n\n**What you'll see (simplified):**\n\n```bash\nCreating silah_db ... done\nCreating silah_backend ... done\nAttaching to silah_db, silah_backend\nsilah_backend    | Database connected successfully\nsilah_backend    | Migrations applied\nsilah_backend    | Categories seeded\nsilah_backend    | 🚀 Server running on http://localhost:3000\n```\n\n#### 6. Verify Everything Works\n\n- **API:** `http://localhost:3000/api`\n- **Health Check:** `http://localhost:3000/api/health`\n- **API Documentation:** `http://localhost:3000/api/docs`\n\n### Method 2: Without Docker (Manual Setup)\n\nIf you prefer to run PostgreSQL locally or have specific requirements.\n\n#### 1-3. Same as Docker method (clone, install, configure)\n\n#### 4. Set Up Local PostgreSQL\n\nMake sure PostgreSQL is running locally and create the database:\n\n```bash\n# Connect to PostgreSQL\npsql -U postgres\n\n# Create user and databases\nCREATE USER silah_user WITH PASSWORD 'your_secure_password';\nCREATE DATABASE silah_dev OWNER silah_user;\nCREATE DATABASE silah_test OWNER silah_user;\nGRANT ALL PRIVILEGES ON DATABASE silah_dev TO silah_user;\nGRANT ALL PRIVILEGES ON DATABASE silah_test TO silah_user;\n```\n\n#### Enable Fuzzy Search Extension (`pg_trgm`)\n\nTo enable typo-tolerant search (e.g., \"Candle\" → \"Candl\"), you **must** enable the `pg_trgm` extension in both databases:\n\n````sql\n\\c silah_dev\nCREATE EXTENSION IF NOT EXISTS pg_trgm;\n\n\\c silah_test\nCREATE EXTENSION IF NOT EXISTS pg_trgm;\n```\n\n\u003e Warning: This extension is required for full-text fuzzy search in products, suppliers, and categories. Without it, search queries will fail.\n\n#### 5. Set Up Prisma and Database\n\n```bash\n# Generate Prisma client\nnpx prisma generate\n\n# Run migrations (development)\nnpm run prisma:dev\n\n# Seed the database with categories (REQUIRED)\nnpm run prisma:seed:category\n````\n\n**Important:** The category seeding step is crucial. It inserts ~50 predefined categories that the application relies on. Skipping this will break category-related features.\n\n#### 6. Start the Server\n\n```bash\nnpm run start:dev\n```\n\n---\n\n## Docker Management\n\n### Available Commands\n\n| Command                  | Description                         | Use Case                          |\n| ------------------------ | ----------------------------------- | --------------------------------- |\n| `npm run docker:dev`     | Start development environment       | Daily development                 |\n| `npm run docker:dev:d`   | Start dev environment in background | When you want to free up terminal |\n| `npm run docker:test`    | Start test environment              | Running integration/e2e tests     |\n| `npm run docker:down`    | Stop all containers                 | Cleanup when done                 |\n| `npm run docker:logs`    | View container logs                 | Debugging issues                  |\n| `npm run docker:cleanup` | Remove containers \u0026 clean system    | Full reset                        |\n\n### Understanding the Docker Setup\n\n```yml\n# Two separate databases for isolation\npostgres_dev: # Development DB on port 5432\npostgres_test: # Test DB on port 5433 (ephemeral data)\n\n# One application container\napp: # NestJS backend on port 3000\n```\n\n**Why separate test database?**\n\n- **Isolation:** Tests doon't interfere with development data\n- **Clean slate:** Each test run starts fresh\n- **Speed:** No need to clean up test data\n- **Safety:** Can't accidentally delete dev data during testing\n\n### Docker Environment Switching\n\nOur Docker setup intelligently switches between development and test configurations:\n\n```bash\n# Development mode\nnpm run docker:dev\n# → Uses .env.dev, connects to postgres_dev, hot reload enabled\n\n# Test mode\nnpm run docker:test\n# → Uses .env.test, connects to postgres_test, optimized for testing\n```\n\n### Troubleshooting Docker\n\n**Port 5432 already in use:**\n\n```bash\n# Kill any processes using the port\nnpm run kill:5432\n\n# Or stop local PostgreSQL service\nbrew services stop postgresql  # macOS\nsudo systemctl stop postgresql  # Linux\n```\n\n**Containers won't start:**\n\n```bash\n# Full cleanup and restart\nnpm run docker:cleanup\nnpm run docker:dev\n```\n\n**Database connection issues:**\n\n```bash\n# Check container logs\nnpm run docker:logs\n\n# Check if database is ready\nnpm run db:wait:dev\n```\n\n---\n\n### Monitoring \u0026 Logging\n\n#### Application Logs\n\n```bash\n# View real-time logs\nnpm run docker:logs\n\n# View specific service logs\ndocker logs silah_backend -f\ndocker logs silah_db -f\n\n# Search logs for specific events (e.g., errors)\ndocker logs silah_backend 2\u003e\u00261 | grep \"ERROR\"\n```\n\n#### Database Monitoring\n\n```bash\n# Connect to database\ndocker exec -it silah_db psql -U silah_user -d silah_dev\n\n# View active connections\nSELECT * FROM pg_stat_activity;\n\n# Monitor query performance\nSELECT * FROM pg_stat_statements ORDER BY mean_time DESC;\n```\n\n---\n\n## Testing Strategy\n\nWe use a comprehensive 3-tier testing approach:\n\n### 1. Unit Tests (`*.spec.ts`)\n\nTest individual components in isolation with mocked dependencies.\n\n```bash\n# Run all unit tests\nnpm test\n\n# Run in watch mode (for development)\nnpm run test:watch\n\n# Run with coverage report\nnpm run test:cov\n\n# Debug tests\nnpm run test:debug\n```\n\n**What unit tests cover:**\n\n- Individual service methods\n- Controller endpoints (mocked dependencies)\n- Utility functions\n- Validation logic\n\n### 2. Integration Tests (`*.int-spec.ts`)\n\nTest multiple components working together with real database connections.\n\n```bash\n# Run integration tests (automatically manages test database)\nnpm run test:int\n```\n\n**What integration tests cover:**\n\n- Controller + Service workflows\n- Service + Database interactions\n- Real database operations\n\n**How integration tests work:**\n\n1. Automatically starts test database container\n2. Waits for database to be ready\n3. Runs migrations and seeds data\n4. Executes tests with real database connections\n5. Cleans up after completion\n\n### 3. End-to-End Tests (`*.e2e-spec.ts`)\n\nTest complete user workflows through HTTP requests.\n\n```bash\n# Run e2e tests\nnpm run test:e2e\n```\n\n**What E2E tests cover:**\n\n- Complete API workflows\n- Authentication \u0026 Authorization\n- Cross-module interaction\n- Real HTTP request/response cycles\n\n### Test Configuration Files\n\n- **Unit Tests:** Uses default Jest configuration in `package.json`\n- **Integration Tests:** `test/jest-int.json`\n- **E2E Tests:** `test/jest-e2e.json`\n\n### Test Database Management\n\n**Development Database (postgres_dev):**\n\n- Local Port: 5432\n- Persistent data (survives container restarts)\n- Used for: Manual testing, development\n\n**Test Database (postgres_test):**\n\n- Local Port: 5433\n- Ephemeral data (fresh start each time)\n- Used for: Integration and E2E tests\n- Automatically managed by test scripts\n\n### Running Tests in Different Scenarios\n\n```bash\n# Quick feedback loop during development\nnpm run test:watch\n\n# Before committing changes\nnpm run test \u0026\u0026 npm run test:int\n\n# Full test suite (CI/CD pipeline)\nnpm test \u0026\u0026 npm run test:int \u0026\u0026 npm run test:e2e\n\n# Coverage report\nnpm run test:cov\n```\n\n---\n\n## Development Workflow\n\n### Daily Development Commands\n\n```bash\n# Start development environment\nnpm run docker:dev\n\n# Watch code changes\nnpm run start:dev  # (if not using Docker)\n\n# Run tests as you develop\nnpm run test:watch\n\n# Check code quality\nnpm run lint\nnpm run format\n\n# Database operations\nnpm run prisma:dev            # Run new migrations\nnpm run prisma:seed:category  # Reseed categories\n```\n\n### Database Operations\n\n```bash\n# Development database migrations\nnpm run prisma:dev\n\n# Test database migrations\nnpm run prisma:test\n\n# Generate Prisma client (after schema changes)\nnpx prisma generate\n\n# Reset database (⚠️ destroys all data)\nnpx prisma migrate reset\n\n# View database in Prisma Studio\nnpx prisma studio\n```\n\n### Code Quality \u0026 Standards\n\n```bash\n# Lint and auto-fix issues\nnpm run lint\n\n# Format code consistently\nnpm run format\n\n# Type checking\nnpm run build\n\n# Pre-commit checks (recommended)\nnpm run lint \u0026\u0026 npm run test \u0026\u0026 npm run build\n```\n\n---\n\n## API Documentation (Swagger UI)\n\n- **Local (runtime):** http://localhost:3000/api/docs\n- **Static (GitHub Pages):** https://gp-silah.github.io/silah-backend/swagger\n\n\u003e Local means once your server is running comprehensive API documentation is available at:\n\u003e **URL:** `http://localhost:3000/api/docs`\n\n**Features:**\n\n- Interactive API explorer\n- Request/response schemas\n- Try-it-out functionality\n- Authentication examples\n- Detailed endpoint descriptions\n\n---\n\n## Troubleshooting Guide\n\n### Common Issues \u0026 Solutions\n\n#### Port 5432 already in use\n\n```bash\n# Solution 1: Kill process using the port\nnpm run kill:5432\n\n# Solution 2: Stop local PostgreSQL\nbrew services stop postgresql  # macOS\nsudo systemctl stop postgresql  # Linux\n\n# Solution 3: Use different port in .env\nDATABASE_URL=postgresql://user:pass@localhost:5433/db\n```\n\n#### Database connection refused\n\n```bash\n# Check if database container is running\ndocker ps | grep silah_db\n\n# Restart database\nnpm run docker:down\nnpm run docker:dev\n\n# Check database logs\ndocker logs silah_db\n```\n\n#### Prisma client not generated\n\n```bash\n# Generate Prisma client\nnpx prisma generate\n\n# Restart your application\nnpm run start:dev\n```\n\n#### Missing categories in database\n\n```bash\n# Reseed categories\nnpm run prisma:seed:category\n\n# Or reset and reseed entire database (this destroys all data)\nnpx prisma migrate reset\n```\n\n#### Docker containers won't start\n\n```bash\n# Full cleanup\nnpm run docker:cleanup\n\n# Check Docker daemon\ndocker --version\ndocker info\n\n# Restart Docker service\nsudo systemctl restart docker  # Linux\n# Restart Docker Desktop on macOS/Windows\n```\n\n#### Tests failing randomly\n\n```bash\n# Clear Jest cache\nnpx jest --clearCache\n\n# Run tests individually\nnpm test -- --testNamePattern=\"specific test name\"\n\n# Check test database\nnpm run docker:test\ndocker logs silah_db_test\n```\n\n#### Hot reload not working\n\n```bash\n# Check volume mounts in docker-compose.override.yml\n# Ensure you're using the override file:\nnpm run docker:dev  # This includes the override file\n\n# If still not working, restart with clean build:\nnpm run docker:down\nnpm run docker:dev\n```\n\n## Getting Help\n\nIf you're still experiencing issues:\n\n1. Check the logs first: `npm run docker:logs`\n2. Verify environment variables are set correctly\n3. Ensure all required services are running\n4. Check GitHub Issues for known problems\n5. Contact the development team\n\n---\n\n## License\n\nThis project is licensed under the terms specified in the LICENSE file.\n\n---\n\n\u003e Built with care by Silah's Backend Team, as a requirement of a Graduation Project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgp-silah%2Fsilah-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgp-silah%2Fsilah-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgp-silah%2Fsilah-backend/lists"}