KAAA Tender Management System
Quick Start Manual

Version: 0.1.0
Last Updated: April 2026
Technology: T3 Stack (Next.js 15, TypeScript, Prisma, tRPC)

1. System Overview

The KAAA Tender Management System is a comprehensive web-based platform designed to manage the complete tender lifecycle — from project creation and tender publishing to vendor bidding, comparative analysis, board review, and contract awards.

Key Features

• Role-Based Access Control — Six distinct user roles with specific permissions
• Project Management — Create and manage infrastructure projects with budgets and timelines
• Tender Bundles — Group items into tender bundles (Project-based or Category-based)
• Vendor Portal — Dedicated interface for vendors to view tenders and submit bids
• Bid Management — Track bid submissions, approvals, and revisions
• Comparative Analysis — Automated comparison of vendor bids
• Board Review — Digital voting and decision tracking by board members
• Award Management — Generate award letters and track rejections
• Audit Trail — Complete logging of all system actions

2. Prerequisites

3. Installation & Setup

Step 1: Clone the Repository

git clone <repository-url>
cd kaaa-tender

Step 2: Install Dependencies

npm install

This will automatically run prisma generate after installation (configured in postinstall script).

Step 3: Configure Environment Variables

Create a .env file in the root directory:

DATABASE_URL="postgresql://username:password@localhost:5432/kaaa_tender"
AUTH_SECRET="your-secret-key-here"
NODE_ENV="development"

Step 4: Set Up the Database

# Push schema to database (development only)
npm run db:push

# OR create a migration and apply it
npm run db:generate
npm run db:migrate

# Seed the database with initial data
npm run db:seed

Step 5: Start the Development Server

npm run dev

Open http://localhost:3000 in your browser.

4. Development Workflow

Daily Development Commands

Database Management

Production Build

# Build for production
npm run build

# Start production server
npm run start

# Or build and preview locally
npm run preview

5. User Roles & Permissions

6. Tender Process Workflow

Complete Process Flow

1. Project Creation — Define project details, budget, fiscal year, and project type
2. Item Setup — Add items from master catalog or create project-specific items
3. Bundle Creation — Group items into a TenderBundle (Project) or CategoryBundle (Category)
4. Tender Notice — Publish tender with eligibility criteria and submission deadline
5. Vendor Invitation — Invite vendors to participate in the tender
6. Bid Submission — Vendors submit bids with quoted rates for each item
7. Bid Approval — Internal staff approve/reject vendor bids
8. Comparative Analysis — System generates comparison of all approved bids
9. Board Review — Board members review analysis and vote
10. Award Decision — Award contract to winning vendor, reject others
11. Documentation — Generate award letters and rejection notices

Tender Status Flow

7. Project Structure

kaaa-tender/
├── prisma/
│   ├── schema.prisma          # Database schema definition
│   ├── seed.ts                # Database seed script
│   └── migrations/            # Database migration files
├── public/                    # Static assets
├── src/
│   ├── app/                   # Next.js App Router pages
│   │   ├── (dashboard)/       # Dashboard layout group
│   │   ├── login/             # Authentication pages
│   │   ├── register/          # User registration
│   │   ├── reports/           # Reports and analytics
│   │   └── vendor-portal/     # Vendor-facing pages
│   ├── components/            # Reusable UI components
│   │   ├── bid/               # Bid-related components
│   │   ├── items/             # Item management components
│   │   └── ui/                # Base UI components (shadcn)
│   ├── server/                # Backend logic
│   │   ├── routers/           # tRPC API routers
│   │   ├── services/          # Business logic services
│   │   └── trpc.ts            # tRPC configuration
│   ├── lib/                   # Utility libraries
│   │   ├── hooks/             # React Query hooks
│   │   ├── formatters/        # Data formatting utilities
│   │   ├── auth.ts            # NextAuth configuration
│   │   ├── db.ts              # Prisma client instance
│   │   └── utils.ts           # General utilities
│   ├── trpc/                  # tRPC client setup
│   └── styles/                # Global CSS styles
├── .env                       # Environment variables (DO NOT COMMIT)
├── package.json               # Node.js dependencies
└── README.md                  # Project documentation

8. Key Technologies Explained

Next.js 15 (App Router)

React framework with file-based routing. Uses the App Router with server-side rendering and client-side navigation.

TypeScript

Type-safe JavaScript that catches errors during development and improves code maintainability.

Prisma ORM

Type-safe database ORM for PostgreSQL. Schema defined in prisma/schema.prisma.

tRPC

Type-safe API layer between frontend and backend. No code generation needed — types are inferred automatically.

NextAuth.js v5

Authentication library with support for multiple providers, JWT sessions, and role-based access control.

Tailwind CSS v4

Utility-first CSS framework for rapid UI development. Custom design system with shadcn/ui components.

9. API Structure (tRPC Routers)

Procedure Types

10. Database Schema Overview

Core Entities

• User — System users with roles and permissions
• Vendor — External companies that submit bids
• Project — Infrastructure projects with budgets
• Item — Master catalog of items (materials, labor, etc.)
• ProjectSpecificItem — Custom items created for specific projects
• TenderBundle / CategoryBundle — Groups of items for tendering
• TenderNotice — Published tender announcements
• BidSubmission — Vendor bid submissions
• ComparativeAnalysis — Bid comparison records
• BoardDecision — Board member votes and decisions
• AwardRecord — Contract award records
• AuditLog — Complete audit trail of all actions

11. Common Tasks

Creating a New Project

1. Log in as PROJECT_MANAGER or SUPER_ADMIN
2. Navigate to Dashboard → Projects
3. Click "Create New Project"
4. Fill in project details (name, code, budget, fiscal year, type)
5. Save the project

Setting Up a Tender

1. Open the project
2. Add items (from master catalog or create project-specific)
3. Create a TenderBundle and add items
4. Set estimated rates and quantities
5. Create a TenderNotice linked to the bundle
6. Set submission deadline and eligibility criteria
7. Publish the tender

Inviting Vendors

1. Open the published TenderNotice
2. Click "Invite Vendors"
3. Select vendors from the registered vendor list
4. Send invitations (email notifications sent automatically)

Reviewing Bids

1. Navigate to the TenderNotice → Submissions
2. Review each bid submission
3. Approve or reject individual bids
4. Generate Comparative Analysis once all bids are approved

12. Troubleshooting

13. Deployment

Deploying to Vercel (Recommended)

1. Push your code to a Git repository (GitHub, GitLab, Bitbucket)
2. Import the project in Vercel
3. Set environment variables in Vercel project settings
4. Deploy — Vercel will run npm run build automatically

Environment Variables for Production

AUTH_SECRET="strong-production-secret"
DATABASE_URL="postgresql://prod-db-url"
NODE_ENV="production"

14. Additional Resources

• Next.js Docs: https://nextjs.org/docs
• Prisma Docs: https://prisma.io/docs
• tRPC Docs: https://trpc.io
• NextAuth.js: https://next-auth.js.org
• Tailwind CSS: https://tailwindcss.com
• T3 Stack: https://create.t3.gg

This manual provides a quick start guide for the KAAA Tender Management System. For detailed technical documentation, refer to the inline code comments and the official documentation of the respective technologies used.