A comprehensive backend API system for managing land plots, tracking sales transactions, calculating commissions, and generating reports for Gbewaa Palace.

The CLMS is built with Node.js and Express.js, using SQLite for data persistence and JWT for authentication. The system follows a layered architecture with clear separation of concerns.

• Runtime: Node.js
• Framework: Express.js
• Database: SQLite (lightweight, file-based)
• ORM: Sequelize
• Authentication: JWT (JSON Web Tokens)
• Password Hashing: bcrypt
• PDF Generation: PDFKit
• Environment Management: dotenv

gbewaa-clms/
├── config/
│   └── db.js                 # Database configuration
├── controllers/
│   ├── authController.js     # Authentication endpoints
│   ├── landController.js     # Land management endpoints
│   ├── transactionController.js # Transaction endpoints (planned)
│   └── reportsController.js  # Reporting endpoints (planned)
├── middlewares/
│   ├── auth.js              # JWT verification & role-based access
│   └── validation.js        # Input validation utilities
├── models/
│   ├── index.js             # Model relationships
│   ├── User.js              # User model with roles
│   ├── LandPlot.js          # Land plot model
│   └── Transaction.js       # Transaction model
├── routes/
│   ├── auth.js              # Authentication routes
│   ├── lands.js             # Land management routes
│   ├── transactions.js      # Transaction routes (planned)
│   └── reports.js           # Reports routes (planned)
├── services/
│   ├── authService.js       # Authentication business logic
│   ├── landService.js       # Land management business logic
│   ├── transactionService.js # Transaction business logic (planned)
│   └── reportsService.js    # Reports business logic (planned)
├── tests/                   # Test files
├── utils/                   # Utility functions
├── .env                     # Environment variables
├── database.sqlite          # SQLite database file
├── package.json             # Dependencies and scripts
└── server.js                # Application entry point

• Node.js (v14 or higher)
• npm or yarn

1. Clone the repository

   git clone <repository-url>
   cd clms-api

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Initialize the database

   node tests/test-db.js

5. Start the server

   npm run dev  # Development mode with nodemon
   # or
   npm start    # Production mode

The server will start on http://localhost:3000

• ADMIN: Full system access including user management
• STAFF: Land management, transaction recording, receipt generation
• AUDITOR: Read-only access to reports and transaction data

1. Login: POST /api/auth/login
2. Get JWT token: Include in Authorization header as Bearer <token>
3. Access protected routes: Token verified on each request

Create the first admin user:

node tests/test-auth-service.js

• page: Page number (default: 1)
• limit: Items per page (default: 10, max: 100)
• status: Filter by status (AVAILABLE, SOLD, DISPUTED, RESERVED)
• location: Filter by location (partial match)
• sortBy: Sort field (plotNumber, location, size, status, etc.)
• sortOrder: Sort order (ASC, DESC)

• AVAILABLE: Ready for sale
• SOLD: Transaction completed
• DISPUTED: Under dispute resolution
• RESERVED: Reserved for specific buyer

• ACRES: Imperial measurement
• HECTARES: Metric measurement
• SQ_METERS: Square meters

# Test database connection
node tests/test-db.js

# Test user model
node tests/test-user-model.js

# Test land plot model
node tests/test-landplot-model.js

# Test transaction model
node tests/test-transaction-model.js

# Test authentication service
node tests/test-auth-service.js

# Test authentication middleware
node tests/test-auth-middleware-simple.js

# Test land service
node tests/test-land-service.js

# Test land endpoints
node tests/test-land-endpoints.js

# Test authentication endpoints
node tests/test-auth-endpoints.js

• ✅ Database connection and synchronization
• ✅ User model with authentication
• ✅ Land plot model with validation
• ✅ Transaction model with relationships
• ✅ Authentication service (register, login, JWT)
• ✅ Authentication middleware (token verification, roles)
• ✅ Land service (CRUD operations)
• ✅ Land controller (API endpoints)
• ✅ Error handling and validation

• Database Setup: SQLite with Sequelize ORM
• User Management: Registration, authentication, role-based access
• Land Management: Full CRUD operations with filtering and pagination
• Security: JWT authentication, password hashing, input validation
• Testing: Comprehensive test suite for all implemented features

• Transaction Management: Sales recording with commission calculation
• PDF Receipt Generation: Automated receipt creation
• Reporting System: Business analytics and summaries
• API Documentation: Swagger/OpenAPI documentation
• Frontend Interface: Web dashboard (future phase)

# Database Configuration
DB_PATH=./database.sqlite
NODE_ENV=development

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=24h

# Server Configuration
PORT=3000

# Application Settings
COMMISSION_RATE=0.10

The system uses SQLite for simplicity and portability:

• File: database.sqlite (created automatically)
• No server setup required
• Easy backup: Just copy the database file
• Development friendly: Reset by deleting the file

• Password Hashing: bcrypt with 12 salt rounds
• JWT Tokens: Secure authentication with expiration
• Role-Based Access: Different permissions for different user types
• Input Validation: Prevent SQL injection and malicious data
• Error Handling: Secure error messages without sensitive data exposure

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": [] // Optional validation details
  }
}

1. Follow the existing code structure and patterns
2. Write tests for new features
3. Use meaningful commit messages
4. Update documentation for API changes

This project is proprietary software for Custom Land Commision.

For technical support or questions:

• Check the test files for usage examples
• Review the API endpoint documentation above
• Examine the service layer for business logic implementation