# KAAA Tender Management System - User Manual

## Table of Contents

1. [System Overview](#1-system-overview)
2. [Technology Stack](#2-technology-stack)
3. [User Roles & Permissions](#3-user-roles--permissions)
4. [Core Modules](#4-core-modules)
5. [Data Model](#5-data-model)
6. [Workflows](#6-workflows)
7. [Technical Architecture](#7-technical-architecture)

---

## 1. System Overview

The KAAA Tender Management System is a comprehensive web-based application designed to manage the complete tendering lifecycle for construction and procurement projects. It supports two tendering models:

- **Project-Based Tendering**: Individual projects are tendered separately
- **Category-Based Tendering (Hybrid)**: Multiple projects are grouped by item category and tendered as a single bundle

Key capabilities include:

- Project and item registry management
- Tender creation, publication, and bid collection
- Vendor management and invitation
- Bid submission and comparison
- Comparative analysis and board decision making
- Award record generation
- Audit logging and notifications

---

## 2. Technology Stack

| Component        | Technology                   |
| ---------------- | ---------------------------- |
| Frontend         | Next.js 15 (React 19)        |
| UI Framework     | Tailwind CSS + shadcn/ui     |
| API Layer        | tRPC v11                     |
| Database         | PostgreSQL                   |
| ORM              | Prisma 6                     |
| Authentication   | NextAuth.js 5                |
| Validation       | Zod                          |
| State Management | React Query (TanStack)       |
| File Export      | xlsx, jspdf, jspdf-autotable |

---

## 3. User Roles & Permissions

| Role              | Description                |
| ----------------- | -------------------------- |
| `SUPER_ADMIN`     | Full system access         |
| `PROJECT_MANAGER` | Create and manage projects |
| `ADMIN_STAFF`     | Administrative operations  |
| `FINANCE_OFFICER` | Financial review access    |
| `BOARD_MEMBER`    | Review and approve tenders |
| `VENDOR`          | Submit bids (external)     |

---

## 4. Core Modules

### 4.1 Dashboard (`/`)

- Overview of active tenders, recent activities, and key metrics

### 4.2 Projects (`/projects`)

- **Purpose**: Register and manage construction projects
- **Features**:
  - Create/edit projects with code, name, description, division, province, budget
  - Associate with fiscal year and project type
  - Add project-specific items (non-catalog items)
  - Generate BOQ from project items or tender bundle items

### 4.3 Items (`/items`)

- **Purpose**: Master items registry
- **Features**:
  - Create/edit items with code, name, unit, category
  - Import items via Excel (bulk import)
  - Item categories (hierarchical)
  - Item status management (Active, Discontinued, Under Review)

### 4.4 Rates (`/rates`)

- **Purpose**: Manage item rates by fiscal year
- **Features**:
  - Set estimated rates for items per fiscal year
  - Track rate source and justification
  - Historical rate tracking

### 4.5 BOQ (`/boq`)

- **Purpose**: Bill of Quantities management
- **Features**:
  - Generate BOQ from project items
  - Create tender bundles from BOQ
  - Export to Excel/PDF

### 4.6 Tenders (`/tenders`)

- **Purpose**: Project-based tendering
- **Tender Flow**:
  1. Draft → 2. Published → 3. Submissions Received → 4. Under Analysis → 5. Board Review → 6. Awarded/Rejected
- **Features**:
  - Create tender from project BOQ
  - Invite vendors
  - Accept/withdraw bids
  - Comparative analysis

### 4.7 Category Tenders (`/tenders/category`)

- **Purpose**: Category-based (hybrid) tendering
- **Features**:
  - Group multiple projects by item category
  - Aggregate quantities across projects
  - Version control for bundles
  - Per-project quantity breakdown

### 4.8 Vendors (`/vendors`)

- **Purpose**: Vendor registry
- **Features**:
  - Vendor registration and profiles
  - Verification status (Pending, Verified, Rejected)
  - Document management
  - Invite to tenders

### 4.9 Vendor Portal (`/vendor-portal`)

- **Purpose**: External vendor interface
- **Features**:
  - View invited tenders
  - Submit bids with line items
  - View bid status

### 4.10 Bids Management (`/tender/[id]/bids`)

- **Purpose**: Bid submission and management
- **Statuses**: Draft → Pending Approval → Submitted → Withdrawn → Approved/Rejected
- **Features**:
  - Bid comparison table
  - Approval workflow
  - Version history

### 4.11 Analysis (`/analysis`)

- **Purpose**: Comparative analysis
- **Features**:
  - Compare bids by item
  - Score card evaluation
  - Recommendation generation

### 4.12 Board (`/board`)

- **Purpose**: Board decision management
- **Features**:
  - Configure board members per fiscal year
  - Voting and decision tracking
  - Quorum-based decisions

### 4.13 Awards (`/awards`)

- **Purpose**: Award record management
- **Features**:
  - Generate award letters
  - Track rejection records
  - Award history

### 4.14 Reports (`/reports`)

- **Purpose**: Reporting and analytics

### 4.15 Audit (`/audit`)

- **Purpose**: Audit log viewer

### 4.16 Settings (`/settings`)

- **Purpose**: System configuration
- **Features**:
  - Fiscal year management
  - System settings

---

## 5. Data Model

### Core Entities

```
FiscalYear
├── id, year, startDate, endDate, isActive
├── projects[], tenderNotices[], itemRates[], categoryBundles[]

Category (Hierarchical)
├── id, name, code, description, parentId
├── items[]

Item (Master Items)
├── id, code, name, description, unit, categoryId, status
├── itemRates[], projectItems[], tenderBundleItems[]

ProjectSpecificItem (Custom per Project)
├── id, code, name, description, unit, projectId

Project
├── id, code, name, description, division, province, budget
├── fiscalYearId, typeId, createdById
├── tenderBundles[], projectItems[], tenderNotices[]

ItemRate (per Fiscal Year)
├── id, itemId, fiscalYearId, rate, source, justification

TenderBundle (Project-based Tender)
├── id, code, projectId, name, description, estimatedTotal, status
├── tenderBundleItems[], tenderNotices[]

TenderBundleItem
├── id, bundleId, itemId, quantity, estimatedRate, specifications
├── source: MASTER_ITEM | PROJECT_SPECIFIC_ITEM

CategoryBundle (Hybrid Tender)
├── id, code, name, fiscalYearId, categoryId, status, version
├── items[], includedProjects[], revisions[]

CategoryBundleItem
├── id, bundleId, itemId, aggregatedQty, estimatedRate, estimatedTotal
├── sources[] (per project breakdown)

TenderNotice (Published Tender)
├── id, referenceNo, title, description, eligibility
├── submissionDeadline, status, tenderType
├── projectId?, categoryBundleId?, fiscalYearId
├── bidSubmissions[], vendorInvites[]

BidSubmission
├── id, tenderId, vendorId, referenceNo, status, totalAmount
├── submittedAt, approvedAt, approvedById, rejectedAt, rejectedById
├── bidLineItems[], versions[]

BidLineItem
├── id, submissionId, itemId, quotedRate, quantity, totalAmount
├── source: MASTER_ITEM | PROJECT_SPECIFIC_ITEM

ComparativeAnalysis
├── id, tenderId, preparedById, analysisData, recommendation
├── scoreData, conditions, submittedAt
├── boardDecisions[]

BoardDecision
├── id, analysisId, memberId, decision, remarks, votedAt

AwardRecord
├── id, tenderId, vendorId, referenceNo, totalAmount
├── awardLetterPath, fiscalYearId, awardedAt
├── rejections[]

Vendor
├── id, name, email, phone, vatPan, address
├── contactPerson, status, verificationStatus
├── bidSubmissions[], tenderInvites[]

User
├── id, name, email, password, role, isActive
├── projects[], comparativeAnalysis[], boardDecisions[]

AuditLog
├── id, userId, action, entityType, entityId, changes, ipAddress

Notification
├── id, userId, type, title, message, link, readAt
```

---

## 6. Workflows

### 6.1 Project-Based Tendering Flow

```
1. Create Project
   └── Add Project Items (with quantity, estimated rate)
       └── OR Add Project-Specific Items

2. Create Tender Bundle (BOQ)
   └── Add items from project items
       └── Set quantities and specifications

3. Create Tender Notice
   └── Select tender bundle
       └── Set eligibility criteria
       └── Set submission deadline

4. Publish Tender
   └── Status: DRAFT → PUBLISHED

5. Invite Vendors
   └── Vendors receive notification

6. Receive Bids
   └── Status: SUBMISSIONS_RECEIVED

7. Submit for Analysis
   └── Status: UNDER_ANALYSIS

8. Comparative Analysis
   └── Generate analysis with recommendations

9. Board Review
   └── Status: BOARD_REVIEW
   └── Board members vote (Approve/Reject/Return)

10. Award Tender
    └── Status: AWARDED
    └── Generate award record
```

### 6.2 Category-Based (Hybrid) Tendering Flow

```
1. Create Category Bundle
   └── Select category and fiscal year

2. Add Projects
   └── Include multiple projects in bundle

3. Add Items
   └── Items are aggregated from all projects
   └── Per-project quantity breakdown tracked

4. Create Tender Notice
   └── Links to category bundle

5. Similar flow as project-based from step 4
```

### 6.3 Vendor Bidding Flow

```
1. Receive Invitation
   └── View tender notice

2. Submit Bid (Draft)
   └── Add line items with quoted rates
   └── Calculate totals

3. Submit Bid
   └── Status: SUBMITTED
   └── Receive confirmation

4. Track Status
   └── Pending Approval → Approved/Rejected
```

---

## 7. Technical Architecture

### API Structure (tRPC Routers)

```
appRouter
├── auth            - Authentication procedures
├── user            - User management
├── category       - Item categories CRUD
├── item           - Master items CRUD
├── project        - Project management
├── projectSpecificItem - Custom items CRUD
├── boq            - BOQ generation
├── tender         - Project tender management
├── categoryTender - Category bundle management
├── vendor         - Vendor management
├── bid            - Bid submission management
├── analysis       - Comparative analysis
├── board          - Board decisions
├── award          - Award records
├── rate            - Item rates
├── report         - Reports generation
├── notification   - Notifications
├── settings        - System settings
├── audit          - Audit logs
```

### Key Technical Patterns

- **tRPC Procedures**: All data operations exposed via tRPC routers
- **Zod Validation**: Request/response validation with Zod schemas
- **Prisma Transactions**: Complex operations use Prisma transactions
- **Optimistic Updates**: React Query for optimistic UI updates
- **Audit Logging**: All entity changes tracked via audit service

---

## Appendix: Status Reference

### Tender Statuses

| Status               | Description             |
| -------------------- | ----------------------- |
| DRAFT                | Initial draft           |
| PUBLISHED            | Publicly advertised     |
| SUBMISSIONS_RECEIVED | Bids received           |
| UNDER_ANALYSIS       | Being analyzed          |
| BOARD_REVIEW         | Awaiting board decision |
| AWARDED              | Successfully awarded    |
| REJECTED             | Rejected                |
| RE_TENDERED          | Re-tendered             |

### Bundle Statuses

| Status    | Description   |
| --------- | ------------- |
| DRAFT     | Initial draft |
| PUBLISHED | Advertised    |
| AWARDED   | Awarded       |
| CANCELLED | Cancelled     |

### Bid Statuses

| Status           | Description      |
| ---------------- | ---------------- |
| DRAFT            | In progress      |
| PENDING_APPROVAL | Awaited approval |
| SUBMITTED        | Submitted        |
| WITHDRAWN        | Withdrawn        |
| APPROVED         | Approved         |
| REJECTED         | Rejected         |

### Vendor Statuses

| Status      | Description           |
| ----------- | --------------------- |
| PENDING     | Awaiting verification |
| APPROVED    | Verified and approved |
| REJECTED    | Rejected              |
| DEACTIVATED | Deactivated           |

---

_End of Manual_