KAAA Tender Management System
Complete Work Guide

1. System Overview & Architecture

1.1 Introduction

The KAAA Tender Management System is a comprehensive, web-based platform designed to digitize and streamline the entire tender lifecycle for infrastructure and construction projects. Built on modern web technologies, it provides role-based access for all stakeholders including administrators, project managers, finance officers, board members, and external vendors.

1.2 System Objectives

• Digitize the complete tender process from project inception to contract award
• Provide transparent, auditable workflows for public procurement compliance
• Enable efficient vendor management and bid evaluation
• Generate automated comparative analysis and reports
• Facilitate digital board review and voting processes
• Maintain comprehensive audit trails for accountability

1.3 Technology Stack

1.4 High-Level Architecture

2. Installation & Configuration

2.1 Prerequisites Checklist

2.2 Complete Installation Steps

Step 1: Clone the Repository

git clone https://github.com/your-org/kaaa-tender.git
cd kaaa-tender

Step 2: Install Node.js Dependencies

npm install

Step 3: PostgreSQL Database Setup

# Connect to PostgreSQL as superuser
psql -U postgres

# Create database
CREATE DATABASE kaaa_tender;

# Create a dedicated user (optional but recommended)
CREATE USER kaaa_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE kaaa_tender TO kaaa_user;

# Exit psql
\q

Step 4: Environment Configuration

# Authentication Secret (generate with: openssl rand -base64 32)
AUTH_SECRET="your-super-secret-key-min-32-characters-long"

# Database Connection
DATABASE_URL="postgresql://kaaa_user:your_secure_password@localhost:5432/kaaa_tender?schema=public"

# Environment
NODE_ENV="development"

# Optional: Email Configuration (for Nodemailer)
# SMTP_HOST="smtp.gmail.com"
# SMTP_PORT="587"
# SMTP_USER="your-email@gmail.com"
# SMTP_PASS="your-app-password"
# SMTP_FROM="noreply@kaaa.gov"

Step 5: Database Schema Deployment

# Push schema directly (no migration history)
npm run db:push

# Seed with initial data
npm run db:seed

# Create a migration from schema changes
npm run db:generate

# Apply all pending migrations
npm run db:migrate

# Open Prisma Studio to visually inspect the database
npm run db:studio

Step 6: Start Development Server

npm run dev

2.3 Verifying Installation

3. User Roles & Permissions Matrix

3.1 Role Hierarchy

3.2 Detailed Role Permissions

SUPER_ADMIN

PROJECT_MANAGER

ADMIN_STAFF

FINANCE_OFFICER

BOARD_MEMBER

VENDOR

3.3 Permission Matrix Summary

SA=Super Admin, PM=Project Manager, AS=Admin Staff, FO=Finance Officer, BM=Board Member, VE=Vendor

4. Complete Workflow Processes

4.1 Project Management Workflow

4.1.1 Project Lifecycle

4.1.2 Step-by-Step: Creating a Project

4.1.3 Adding Items to a Project

4.2 Tender Creation & Management

4.2.1 Tender Types

4.2.2 Creating a Project Tender

4.2.3 Creating a Category Tender

4.3 Vendor Management

4.3.1 Vendor Registration Process

4.3.2 Step-by-Step: Vendor Registration (Admin)

4.3.3 Inviting Vendors to Tenders

4.4 Bid Submission Process

4.4.1 Vendor Bid Submission Workflow

4.4.2 Step-by-Step: Vendor Submitting a Bid

4.4.3 Bid Status Flow

4.4.4 Internal Bid Approval

4.5 Comparative Analysis

4.5.1 Analysis Overview

Once all bids are approved, the system generates a comparative analysis that allows evaluators to compare vendor bids across all items, considering both price and weighted importance.

4.5.2 Step-by-Step: Generating Comparative Analysis

4.5.3 Comparative Analysis Output

The analysis can be exported in multiple formats:

4.6 Board Review & Decision

4.6.1 Board Review Process

4.6.2 Board Member: Reviewing and Voting

4.6.3 Quorum and Decision Rules

4.7 Award Management

4.7.1 Award Process

4.7.2 Award Rejection and Re-tendering

5. Technical Architecture

5.1 Application Structure

5.1.1 Next.js App Router Structure

src/app/
├── (dashboard)/              # Protected dashboard routes
│   ├── layout.tsx            # Dashboard layout with sidebar/nav
│   ├── page.tsx              # Dashboard home/overview
│   ├── projects/             # Project management pages
│   ├── tenders/              # Tender management pages
│   ├── vendors/              # Vendor management pages
│   ├── reports/              # Reports and analytics
│   └── board/                # Board review pages
├── vendor-portal/            # Vendor-facing routes
│   ├── layout.tsx            # Vendor portal layout
│   ├── page.tsx              # Vendor dashboard
│   ├── tenders/              # Available tenders
│   └── my-bids/              # Vendor's bid history
├── login/
│   └── page.tsx              # Login page
├── register/
│   └── page.tsx              # Registration page
├── layout.tsx                # Root layout (providers, fonts)
└── page.tsx                  # Root page (redirect to dashboard)

5.1.2 Server Structure (tRPC + Services)

src/server/
├── routers/                  # tRPC routers (API endpoints)
│   ├── auth.router.ts        # Authentication procedures
│   ├── project.router.ts     # Project CRUD
│   ├── tender.router.ts      # Tender management
│   ├── vendor.router.ts      # Vendor operations
│   ├── boq.router.ts         # Bill of Quantities
│   ├── report.router.ts      # Reporting procedures
│   ├── notification.router.ts# User notifications
│   └── index.ts              # Router aggregation
├── services/                 # Business logic layer
│   ├── project.service.ts    # Project operations
│   ├── tender.service.ts     # Tender operations
│   ├── bid.service.ts        # Bid management
│   ├── vendor.service.ts     # Vendor operations
│   ├── award.service.ts      # Award processing
│   ├── analysis.service.ts   # Comparative analysis
│   ├── board.service.ts      # Board decisions
│   ├── rate.service.ts       # Item rate management
│   ├── category.service.ts   # Category operations
│   └── audit.service.ts      # Audit logging
├── trpc.ts                   # tRPC initialization
└── db.ts                     # Prisma client instance

5.2 tRPC Procedure Types and Middleware

5.2.1 Procedure Hierarchy

// publicProcedure - No authentication required
// Used for: Login, registration, public pages
export const publicProcedure = t.procedure;

// protectedProcedure - Any authenticated user
// Used for: Dashboard access, user profile
const enforceUserIsAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) throw new TRPCError({ code: "UNAUTHORIZED" });
  return next({ ctx: { session: { ...ctx.session, user: ctx.session.user } } });
});
export const protectedProcedure = t.procedure.use(enforceUserIsAuthed);

// adminProcedure - Admin roles only
// Used for: Project creation, tender management
export const adminProcedure = protectedProcedure.use(
  enforceRole(["SUPER_ADMIN", "ADMIN_STAFF", "PROJECT_MANAGER"])
);

// superAdminProcedure - Super admin only
// Used for: User management, system settings
export const superAdminProcedure = protectedProcedure.use(
  enforceRole(["SUPER_ADMIN"])
);

// financeProcedure - Finance roles
// Used for: Rate setting, financial approvals
export const financeProcedure = protectedProcedure.use(
  enforceRole(["SUPER_ADMIN", "FINANCE_OFFICER"])
);

// boardProcedure - Board members
// Used for: Board review, voting
export const boardProcedure = protectedProcedure.use(
  enforceRole(["SUPER_ADMIN", "BOARD_MEMBER"])
);

// vendorProcedure - Vendor only
// Used for: Bid submission, vendor portal
export const vendorProcedure = protectedProcedure.use(
  enforceRole(["VENDOR"])
);

5.2.2 Creating a Protected Router

// Example: project.router.ts
import { createTRPCRouter, adminProcedure, protectedProcedure } from "../trpc";
import { z } from "zod";

export const projectRouter = createTRPCRouter({
  // Public list (authenticated users only)
  list: protectedProcedure.query(async ({ ctx }) => {
    return ctx.db.project.findMany({
      where: { ... }
    });
  }),

  // Create (admin only)
  create: adminProcedure
    .input(z.object({
      name: z.string().min(3),
      code: z.string(),
      budget: z.number().positive(),
      fiscalYearId: z.string(),
    }))
    .mutation(async ({ ctx, input }) => {
      return ctx.db.project.create({
        data: { ...input, createdById: ctx.session.user.id }
      });
    }),

  // Delete (super admin only)
  delete: superAdminProcedure
    .input(z.object({ id: z.string() }))
    .mutation(async ({ ctx, input }) => {
      return ctx.db.project.delete({ where: { id: input.id } });
    }),
});

5.3 Data Flow Example

6. Database Schema Reference

6.1 Entity Relationship Overview

The database is designed with PostgreSQL using Prisma ORM. The schema supports the complete tender lifecycle with proper relationships and audit trails.

6.2 Key Models

User Model

model User {
  id            String    @id @default(cuid())
  name          String
  email         String    @unique
  password      String    // bcryptjs hashed
  role          Role      @default(VENDOR)
  isActive      Boolean   @default(true)
  emailVerified DateTime?
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt

  // Relations
  accounts           Account[]
  sessions           Session[]
  projects           Project[]           // Projects created by user
  comparativeAnalysis ComparativeAnalysis[] // Analysis prepared by user
  auditLogs          AuditLog[]
  boardDecisions     BoardDecision[]
  notifications      Notification[]
  categoryBundles    CategoryBundle[]    // Bundles created by user
  bundleRevisions    CategoryBundleRevision[]
  approvedBids       BidSubmission[] @relation("BidApprovals")
  rejectedBids       BidSubmission[] @relation("BidRejections")
}

Vendor Model

model Vendor {
  id                  String       @id @default(cuid())
  name                String
  email               String       @unique
  phone               String?
  vatPan              String       @unique
  address             String?
  contactPerson       String?
  status              VendorStatus @default(PENDING)
  verificationStatus VendorVerificationStatus @default(PENDING)
  createdAt           DateTime     @default(now())
  updatedAt           DateTime     @updatedAt

  // Relations
  bidSubmissions   BidSubmission[]
  rejectionRecords RejectionRecord[]
  awardRecords     AwardRecord[]
  tenderInvites    TenderVendor[]
  documents        VendorDocument[]
}

BidSubmission Model

model BidSubmission {
  id            String    @id @default(cuid())
  tenderId      String
  vendorId      String
  referenceNo   String    @unique
  status        BidStatus @default(DRAFT)
  totalAmount   Decimal?  @db.Decimal(15, 2)
  submittedAt   DateTime?
  approvedAt    DateTime?
  approvedById  String?
  rejectedAt    DateTime?
  rejectedById  String?
  rejectionReason String?
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt

  // Relations
  tender        TenderNotice  @relation(fields: [tenderId], references: [id])
  approvedBy    User?        @relation("BidApprovals", fields: [approvedById], references: [id])
  rejectedBy    User?        @relation("BidRejections", fields: [rejectedById], references: [id])
  vendor        Vendor       @relation(fields: [vendorId], references: [id])
  bidLineItems  BidLineItem[]
  versions      BidVersion[]

  @@unique([tenderId, vendorId]) // One bid per vendor per tender
}

TenderNotice Model

model TenderNotice {
  id                  String       @id @default(cuid())
  referenceNo         String       @unique
  bundleId            String?
  fiscalYearId        String
  title               String
  description         String?
  eligibility         String?
  submissionDeadline  DateTime
  status              TenderStatus  @default(DRAFT)
  tenderType          TenderType    @default(PROJECT)
  projectId           String?
  categoryBundleId    String?        @unique
  publishedAt         DateTime?
  autoApproveBids     Boolean       @default(false)
  createdAt           DateTime     @default(now())
  updatedAt           DateTime     @updatedAt

  // Relations
  bundle           TenderBundle?       @relation(fields: [bundleId], references: [id])
  categoryBundle   CategoryBundle?     @relation(fields: [categoryBundleId], references: [id])
  fiscalYear       FiscalYear         @relation(fields: [fiscalYearId], references: [id])
  project          Project?            @relation(fields: [projectId], references: [id])
  bidSubmissions   BidSubmission[]
  comparativeAnalysis ComparativeAnalysis[]
  awardRecord      AwardRecord?
  vendorInvites    TenderVendor[]
}

6.3 Enums (Lookup Values)

6.4 Relationship Diagram (Simplified)

7. API & tRPC Router Documentation

7.1 Router List

auth.router.ts

project.router.ts

tender.router.ts

vendor.router.ts

boq.router.ts (Bid Submission)

7.2 Using tRPC in Components

// Example: Fetching projects in a component
import { api } from "@/trpc/client";

function ProjectList() {
  // Query data
  const { data: projects, isLoading } = api.project.list.useQuery({
    fiscalYearId: "2026-27"
  });

  // Mutation
  const createProject = api.project.create.useMutation({
    onSuccess: () => {
      // Refetch projects after creation
      utils.project.list.invalidate();
    }
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {projects?.map(project => (
        <div key={project.id}>{project.name}</div>
      ))}
    </div>
  );
}

8. Frontend Component Guide

8.1 Component Organization

src/components/
├── ui/                       # Base shadcn/ui components
│   ├── button.tsx
│   ├── input.tsx
│   ├── dialog.tsx
│   ├── table.tsx
│   └── ...
├── bid/                      # Bid-related components
│   ├── BidComparisonTable.tsx
│   ├── BidStatusBadge.tsx
│   ├── VendorBidFilters.tsx
│   ├── VendorInviteButton.tsx
│   ├── BidApprovalCard.tsx
│   └── index.ts
├── items/                    # Item management components
│   ├── item-selector.tsx
│   ├── project-specific-item-creator.tsx
│   ├── item-source-badge.tsx
│   ├── sort-dropdown.tsx
│   ├── export-button.tsx
│   └── index.ts
└── ...                       # Other feature components

8.2 Key Component Patterns

Server Component (Data Fetching)

// src/app/(dashboard)/projects/[id]/page.tsx
import { api } from "@/trpc/server";

export default async function ProjectPage({ params }: { params: { id: string } }) {
  // Fetch data on the server
  const project = await api.project.getById({ id: params.id });

  return (
    <div>
      <h1>{project.name}</h1>
      <p>Budget: {project.budget}</p>
    </div>
  );
}

Client Component (Interactive)

"use client";

import { api } from "@/trpc/client";
import { useState } from "react";
import { Button } from "@/components/ui/button";

export function CreateBidForm({ tenderId }: { tenderId: string }) {
  const [lineItems, setLineItems] = useState([]);
  const utils = api.useUtils();

  const submitBid = api.boq.submitBid.useMutation({
    onSuccess: () => {
      utils.boq.getMyBids.invalidate();
    }
  });

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      submitBid.mutate({ tenderId, lineItems });
    }}>
      {/* Form fields */}
      <Button type="submit" disabled={submitBid.isPending}>
        Submit Bid
      </Button>
    </form>
  );
}

8.3 Custom Hooks

// src/lib/hooks/use-projects.ts
import { api } from "@/trpc/client";

export function useProjects(fiscalYearId?: string) {
  return api.project.list.useQuery(
    { fiscalYearId },
    { enabled: !!fiscalYearId }
  );
}

export function useCreateProject() {
  const utils = api.useUtils();
  return api.project.create.useMutation({
    onSuccess: () => {
      utils.project.list.invalidate();
    }
  });
}

// Usage in component
function ProjectList() {
  const { data, isLoading } = useProjects("2026-27");
  const createProject = useCreateProject();

  // ...
}

9. Maintenance & Administration

9.1 Database Maintenance

Backup Procedures

# Create a backup
pg_dump -U kaaa_user -d kaaa_tender > backup_$(date +%Y%m%d).sql

# Restore from backup
psql -U kaaa_user -d kaaa_tender < backup_20260429.sql

Prisma Migration Best Practices

Seed Data Management

# Run seed
npm run db:seed

9.2 User Management

Creating Admin Users

Resetting User Password

9.3 Audit Log Review

9.4 System Settings

10. Troubleshooting & FAQ

10.1 Common Issues

Issue: "Database connection failed"

Issue: "Port 3000 already in use"

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# OR use a different port
npm run dev -- -p 3001

Issue: "TypeScript errors during build"

# Check for type errors
npm run typecheck

# Fix errors reported
# Common issues:
# - Missing null checks
# - Incorrect API response types
# - Prisma model changes not reflected

Issue: "tRPC procedure returns 403 Forbidden"

Issue: "Bid submission fails"

10.2 FAQ

Q: Can I change a published tender?
A: No, once a tender is published, most fields cannot be edited. You must create a new version or re-tender.

Q: How do I add a new user role?
A: Update the Role enum in prisma/schema.prisma, run migration, then update the role checks in src/server/trpc.ts.

Q: Can vendors edit submitted bids?
A: Vendors can edit bids that are in DRAFT status. Once SUBMITTED, they can only withdraw (before deadline).

Q: How is the comparative analysis calculated?
A: The system compares quoted rates across vendors, applies item weights, and calculates a weighted score. The formula is customizable in src/server/services/analysis.service.ts.

Q: Can I export data to Excel?
A: Yes, use the export buttons in the UI. The system uses the xlsx library for Excel generation and jsPDF for PDF exports.

Q: How do I configure email notifications?
A: Set SMTP environment variables in .env file. The system uses Nodemailer for sending emails.

Q: What happens if the board doesn't reach quorum?
A: The decision is pending until enough board members vote. Configure quorum requirements in BoardConfig.

11. Deployment Guide

11.1 Deployment Options

11.2 Deploying to Vercel (Recommended)

git add .
git commit -m "Ready for deployment"
git push origin main

11.3 Docker Deployment

# Dockerfile
FROM node:20-alpine AS base

# Install dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Build
COPY . .
RUN npm run build

# Production
FROM node:20-alpine
WORKDIR /app
COPY --from=base /app/.next .next
COPY --from=base /app/node_modules node_modules
COPY --from=base /app/package.json .
COPY --from=base /app/prisma prisma

EXPOSE 3000
CMD ["npm", "start"]

# Build image
docker build -t kaaa-tender .

# Run container
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e AUTH_SECRET="..." \
  --name kaaa-tender \
  kaaa-tender

11.4 Production Checklist

12. Appendices

Appendix A: Environment Variables Reference

Appendix B: Keyboard Shortcuts

Appendix C: Glossary

Appendix D: Contact & Support

KAAA Tender Management System - Complete Work Guide
Version 0.1.0 | Last Updated: April 2026
Document generated for internal use. Do not distribute without authorization.