KrishokOS Technical Reference

KrishokOS — My Complete Build Reference

AI-Powered Agricultural Operating System for Bangladesh

This is my consolidated technical reference for KrishokOS — everything from the vision I started with, through the architecture I designed, to what I’ve actually shipped in the MVP. I wrote this so I (or anyone picking this project up later) can read one document and understand not just what the system does, but why I made the decisions I made along the way.

• Current Build: MVP v1.0
• Actual MVP Tech Stack: Next.js 16 · React 19 · TypeScript · Tailwind CSS · Local JSON Database (MVP) · JWT Authentication · Server + Client Components · REST API Architecture

⚠️ A note before I get into it: I wrote my planning documents at different points in the project, and they don’t all agree with each other — for example, one of my early planning docs recommends a React + Vite + Django + PostgreSQL stack, while what I actually shipped is Next.js end-to-end with a local JSON database. Wherever my own sources conflict, I’ve labeled things clearly as “Vision / Planning” vs. “As-Built” so I never present an old idea as if it were current fact.

Table of Contents

1. My Product Vision
2. My Product Strategy & MVP Philosophy
3. My MVP Scope
4. My Product Feature Roadmap (All Phases)
5. My System Architecture
6. My Technology Stack
7. My Project Structure (As-Built)
8. My Landing Page
9. My Landing Page Refactor History
10. My Internationalization Setup (Bengali ↔ English)
11. My Authentication System
12. My Session & Route Security
13. My User Entry Points & Navigation Flows
14. My Plant Management Module
15. My Farm Setup Wizard
16. My Farm Analysis Engine
17. My Dashboard
18. My Personalized Analytics Engine (As-Built)
19. My Data Models
20. My API Reference
21. My Land Conversion Engine
22. My Security Architecture
23. My Performance Optimizations
24. My Developer Setup
25. My Current MVP User Journey
26. My Future Roadmap
27. Things I Still Need to Reconcile

1. My Product Vision

I’m building KrishokOS to become a Bangladesh-focused Agriculture ERP platform — one designed to help farmers produce residue-free, export-quality crops through guided, data-driven farming practices. I wanted it to feel like real digital infrastructure for smart agriculture, not just another form-heavy dashboard, so I made it Bengali-first from day one rather than bolting on translations later.

My vision statement: empower Bangladesh’s agriculture through technology-driven, safe, sustainable, and export-ready farming.

My long-term goal is an integrated operating system for agriculture spanning multiple farming domains:

• Plant Management
• Livestock Management
• Aquaculture Management

My core value proposition for the MVP: enable Bangladeshi farmers to establish and manage residue-free banana farms through guided onboarding, intelligent recommendations, and actionable cultivation insights.

2. My Product Strategy & MVP Philosophy

I made a deliberate decision not to build a full-scale agricultural ERP from day one. Instead, I’m following a focused, iterative approach:

1. Solve one problem exceptionally well.
2. Support one crop initially.
3. Validate the guided farming experience.
4. Build reusable architecture for future expansion.

By starting with banana cultivation and decision support, I’m establishing a foundation I can evolve into a full agricultural operating system for Bangladesh, rather than trying to boil the ocean on my first release.

3. My MVP Scope

I focused my MVP on five pillars:

1. Authentication System
2. Farm Onboarding Wizard
3. Plant Management Module
4. Personalized Analytics Dashboard
5. Multi-language Support (Bangla + English)

✅ What I included in the MVP

• Banana cultivation management
• Guided farm setup experience
• Farm assessment and recommendation engine
• Decision-support dashboard
• Single farm ownership per user
• Authentication and onboarding workflows

❌ What I deliberately excluded from the MVP

• Multiple crop support
• Multiple farm management
• Livestock management
• Aquaculture management

4. My Product Feature Roadmap (All Phases)

This is the full, long-range roadmap I laid out during planning — it spans well beyond what I’ve actually built for the current MVP.

The development sequence I recommend to myself

1. Landing Page
2. Authentication
3. Farm Setup Wizard
4. Dashboard
5. Crop Journey Timeline
6. Task Management
7. Inventory
8. Harvest Tracking
9. Disease Detection
10. AI Assistant
11. Traceability
12. Marketplace

5. My System Architecture

I use a modern, serverless-first architecture optimized for performance and scalability — at least, that’s the plan. What I’ve actually shipped so far is intentionally leaner than that plan, so I’m documenting both here.

5.1 My Planning-Stage Architecture (Vision)

My original architecture blueprint envisioned a heavier, enterprise-style stack:

                    CLIENT LAYER
                    ------------
        Next.js + TypeScript + Tailwind + ShadCN UI
        • Landing Page
        • Authentication
        • Dashboard
        • Farm Setup Wizard
        • Crop Management
        • Advisory Panel
        • Reports & Analytics
                         │
                         │ HTTPS
                         ▼
                 APPLICATION LAYER
                 -----------------
              Next.js App Router
        • Server Components
        • Route Handlers
        • Server Actions
        • Middleware

  ┌────────────────┬────────────────────┬──────────────────┐
  │ Authentication  │  Business Logic     │  Notifications   │
  ├────────────────┼────────────────────┼──────────────────┤
  │ Clerk/Auth.js   │  Farm Setup         │  In-App Alerts   │
  │ RBAC            │  Crop Planning      │  SMS Gateway     │
  │ Sessions        │  Advisory Engine    │  Email Service   │
  │                 │  Task Scheduler     │                  │
  └────────────────┴────────────────────┴──────────────────┘
                         │
                         ▼
                     DATA LAYER
                     ----------
                 PostgreSQL + Prisma

  Entities:
  • User            • Task
  • Farm            • Inventory
  • Field           • DiseaseReport
  • Crop            • IrrigationSchedule
  • CropCycle       • FertilizerApplication
                    • Harvest
                    • ExportCertificate
                    • Notification
                         │
                         ▼
                 EXTERNAL SERVICES
                 -----------------
  • Cloudinary / S3       → Image Storage
  • OpenAI / Gemini       → AI Advisory
  • SMS Provider          → Notifications
  • Resend / SendGrid     → Email Service
  • Weather APIs          → Forecast Data
  • Government APIs       → Agricultural Data

The deployment flow I planned:

GitHub → Vercel → Next.js Application
                       ├──▶ PostgreSQL
                       ├──▶ Cloudinary
                       └──▶ OpenAI / Gemini

5.2 What I Actually Built — As-Built MVP Architecture

What I’ve shipped is deliberately simpler than the plan above — no external auth provider yet, no Postgres yet, no AI services integrated yet:

┌─────────────────────────┐
│    Landing Website      │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│  Authentication System  │   (JWT-style, JSON-backed)
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│  Plant Management Setup │
│  Crop + Farming Method   │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│    Farm Setup Wizard    │
│   11-Step Onboarding    │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│ Personalized Dashboard  │
│  Analytics + Advisories │
└─────────────────────────┘

Here’s how I’m tracking what I’ve built vs. what I still have planned:

How I think about the request flow once I’m on the planned stack: the Next.js App Router is my orchestration layer — the Client Layer renders the UI (Dashboard, Farm Setup, Reports), the Application Layer handles business logic via Server Components, Route Handlers, and Server Actions, and the Data Layer has Prisma talking to Supabase PostgreSQL across entities like User, Farm, Field, CropCycle, Task, Inventory, and DiseaseReport.

6. My Technology Stack

What I’ve actually shipped — Frontend

What I’ve actually shipped — Backend

An alternative stack I proposed early on (not what I actually shipped)

In one of my earlier planning documents, I proposed a different frontend/backend pairing. I’m keeping it here for historical context, but the actual MVP uses the Next.js full-stack approach above, not this:

• Frontend: React + Vite, with React Router, Context API, React Hook Form, Zod, TanStack Query
• Backend: Django, Django REST Framework, PostgreSQL

7. My Project Structure (As-Built)

app/
│
├── page.tsx
├── layout.tsx
│
├── auth/
│   ├── signin/
│   ├── signup/
│   ├── verify-email/
│   ├── forgot-password/
│   └── resetpassword/
│
├── dashboard/
│
├── wizard/
│
├── plant-management/
│
└── api/
    ├── auth/
    └── wizard/

components/
│
├── landing/
│   ├── Header.tsx
│   ├── HeroSection.tsx
│   ├── ModuleCards.tsx
│   ├── CropsShowcase.tsx
│   └── LandingPage.tsx
│
├── wizard/
│   ├── WizardLayout.tsx
│   ├── ProgressTracker.tsx
│   ├── SuccessModal.tsx
│   └── steps/
│
└── ui/
    └── button.tsx

lib/
│
├── auth.ts
├── wizardDb.ts
├── validation.ts
└── unitConverter.ts

data/
│
├── users.json
├── farmers.json
├── farms.json
├── wizardProgress.json
├── crops.json
└── locations.json

8. My Landing Page

The components I built

Header.tsx

What it’s responsible for:

• Sticky navigation
• Mobile menu
• Language switcher
• Login / Signup CTA

I use useState() for mobile menu management here.

HeroSection.tsx

What it contains:

• Hero title, subtitle, CTA buttons
• KPI statistics
• Advisory preview card

I render all of this data from arrays rather than hardcoding it.

ModuleCards.tsx

What it displays: Plant Management, Financial Management, Advisory System, AI Assistant, Analytics — all rendered via mapped data arrays.

CropsShowcase.tsx

What it displays: the crops I currently support and plan to support — Banana, Papaya, Rice, Mango, Vegetable — using next/image for optimized loading.

The three primary CTAs I designed

My landing page has three CTAs, each with its own journey I mapped out deliberately:

1. Header CTA — “শুরু করুন” (“Get Started”)

Landing Page → Sign Up / Sign In → Dashboard (empty state)

2. Hero CTA — a dashboard-navigation action

Landing Page → Sign Up / Sign In → Dashboard (empty state)

Note to myself: the original label for this CTA got corrupted somewhere in my source documentation and I couldn’t reliably recover it — I need to verify the exact label against my live source code.

3. Hero CTA — “Farm Setup শুরু করুন” (“Start Farm Setup”)

Landing Page → Sign Up / Sign In → 11-Step Farm Setup Wizard → Farm Analysis Engine → Dashboard (active state)

The empty dashboard state I show (after CTAs 1 & 2, before the wizard is completed):

Welcome, [User Name]
You haven't configured your farm yet.
[ Start Farm Setup ]

9. My Landing Page Refactor History

Before: my monolithic Hero.tsx

Originally, my app/page.tsx rendered a single Hero.tsx component that contained the entire landing page: sticky header, hero section, stats/KPIs, advisory panel, module showcase, crop showcase, and mobile nav logic — all crammed into one file.

Supporting files I had at the time:

• button.tsx — a reusable button using class-variance-authority (CVA)
• utils.ts — my cn() helper for merging Tailwind classes
• globals.css — Tailwind imports, theme variables, base styles

After: the decomposed component architecture I moved to

components/
└── landing/
    ├── LandingPage.tsx
    ├── Header.tsx
    ├── HeroSection.tsx
    ├── ModuleCards.tsx
    └── CropsShowcase.tsx

What I changed, step by step

How I simplified Hero.tsx

Before:

Hero.tsx
└── Entire landing page implementation

After:

Hero.tsx
└── Returns <LandingPage />

Since Hero.tsx now just functions as a passthrough wrapper, I can safely remove it entirely, updating page.tsx to:

import LandingPage from "@/components/landing/LandingPage";

export default function Home() {
  return <LandingPage />;
}

How I fixed mobile navigation

What I had before:

document.getElementById(...)

What I moved to:

const [mobileOpen, setMobileOpen] = useState(false);

<button onClick={() => setMobileOpen((prev) => !prev)} />

{mobileOpen && (
  <div>...</div>
)}

This aligns with React best practices, eliminates manual DOM manipulation, and makes the behavior much more predictable and maintainable.

The data-driven rendering pattern I adopted

I generate navigation (and similar UI) from config arrays rather than hardcoding JSX:

const navLinks = [
  { href: "#modules", label: "..." }, // localized label
  { href: "#crops", label: "..." },   // localized label
];

<nav>
  {navLinks.map((link) => (
    <a key={link.href} href={link.href}>
      {link.label}
    </a>
  ))}
</nav>

Note to myself: the actual Bengali label strings got corrupted in one of my source documents during export and are omitted here rather than guessed at — I need to pull the real strings from my live codebase.

What this pattern gets me: less repetitive JSX, centralized content updates, easier scaling.

10. My Internationalization Setup (Bengali ↔ English)

I built KrishokOS Bengali-first, with seamless toggling to English.

The languages I support:

type Language = "bn" | "en";

Where I keep the state — LandingPage.tsx:

const [language, setLanguage] = useState<"bn" | "en">("bn");

How I pass it down:

LandingPage
├── Header
├── HeroSection
├── ModuleCards
└── CropsShowcase

Each child component receives language as a prop; Header owns the toggle controls and updates the shared state:

onClick={() => onLanguageChange("bn")}
onClick={() => onLanguageChange("en")}

My translation object pattern:

const heroText = {
  bn: {
    title: "...", // localized title
  },
  en: {
    title: "Smart Agriculture",
  },
};

<h1>{heroText[language].title}</h1>

Keeping the HTML lang attribute in sync:

useEffect(() => {
  document.documentElement.lang = language === "en" ? "en" : "bn";
}, [language]);

The result I get: users can switch between Bengali and English and every piece of dynamic content updates instantaneously, without heavy routing overhead or manual DOM manipulation.

Something I still want to do: move my translations into dedicated locale files and adopt full Next.js i18n routing instead of the in-component state pattern I’m using right now.

11. My Authentication System

The features I’ve built

My user record schema — data/users.json

{
  "id": "uuid",
  "name": "Farmer Name",
  "email": "user@email.com",
  "phone": "017XXXXXXXX",
  "passwordHash": "...",
  "emailVerified": true,
  "verificationToken": null,
  "resetToken": null,
  "createdAt": ""
}

My planned upgrade path: in my original architecture I envisioned swapping this for NextAuth.js with full RBAC — I haven’t implemented that yet in the MVP.

12. My Session & Route Security

I implemented this in lib/auth.ts.

What I built:

• JWT-style tokens
• HTTP-only cookies (so client-side scripts can’t access the token)
• Session persistence
• Protected routes, gated via requireUser() before rendering

The pages I protect:

• /dashboard
• /wizard
• /plant-management

13. My User Entry Points & Navigation Flows

I require authentication on all of my primary CTAs.

What happens for an unauthenticated user

CTA Click → Redirect to Authentication

My authentication routes:

/auth/signin
/auth/signup

How I handle post-authentication redirects

I make sure users return to whatever they were originally trying to reach:

14. My Plant Management Module

Route: /plant-management

What it’s for: letting the user select a Crop and Farming Method before entering the Farm Setup Wizard.

Crop selection

Farming methods I support

• Residue-Free Farming
• Organic Farming
• Chemical Farming

The workflow I built

Select Crop
     │
     ▼
Select Farming Method
     │
     ▼
POST /api/wizard/start
     │
     ▼
Redirect /wizard

15. My Farm Setup Wizard

Route: /wizard · Purpose: create a Farmer Profile and Farm Profile through an 11-step guided wizard.

Where I drew inspiration from: the Plantix onboarding flow, and the Krishok Smart Farm onboarding experience.

What I built into it: cascading location dropdowns (Division → District → Upazila), dynamic unit conversion, and persistent state management across steps.

⚠️ Something I need to reconcile with myself: across two of my own planning documents, I described the 11 steps slightly differently — different ordering and grouping of fields (e.g. one groups District/Upazila/Union as three separate steps, the other groups Division/District/Upazila into a single step). I’ve kept both versions below until I confirm against my live wizard code (components/wizard/steps/) which one actually shipped.

15.1 The version I documented in my Technical Documentation

Important thing to remember: Step 11 is not an input step. My completion threshold is completedSteps.length >= 10.

15.2 The version I documented in my Banana Farm Setup spec

16. My Farm Analysis Engine

Once someone completes onboarding, my system generates an initial farm assessment automatically.

Example farm profile output

Residue-Free Banana Farm
Rajshahi
2 Acres

The initial recommendations I generate

• Recommended Variety
• Recommended Plant Spacing
• Required Seedling Quantity

The financial estimates I calculate

• Estimated Production Cost
• Expected Revenue
• Projected Profit

The risk assessment I run

• Water Availability Risk
• Soil Suitability Risk
• Climate Considerations

Everything my Farm Analysis Engine generates becomes a widget inside the dashboard.

The data flow I designed (planning doc)

User
  ↓
Farm
  ↓
FarmAssessment
  ↓
CultivationPlan
  ↓
BananaPlan
  ↓
Recommendations
  ↓
Activities

17. My Dashboard

Route: /dashboard — protected, requires an authenticated user.

My dashboard logic

I built the dashboard’s behavior around one condition: has the user completed Farm Setup?

Scenario A — Farm Setup Not Completed → Empty Dashboard

What I display: “No active farms”, “Start your first farm setup”

Primary action: Start Farm Setup

What I keep hidden until onboarding completes:

• Analytics
• Irrigation schedules
• Fertilizer recommendations
• Disease monitoring
• Production timeline

In my actual MVP right now, the empty-state instead shows mock values for early testing rather than a fully blank state — I’m treating this as a known, intentional simplification for now, not the final behavior.

Scenario B — Farm Setup Completed → Active Farm Dashboard

Sections I show:

• Farm Overview (Banana Variety, Farm Size, Farming Method, Expected Harvest Date)
• Today’s Recommendations
• Upcoming Tasks
• Production Timeline
• Alerts
• Recent Activities

18. My Personalized Analytics Engine (As-Built)

Dashboard states in my MVP

What I generate this from

• Crop, Farming Method, Soil Type, Water Source, Land Size, Budget

Farm Profile Overview

I display Farm Name, Crop, Location, Method.

Soil & irrigation advisory (example)

Loamy Soil + Tube Well Water →

• Weekly irrigation schedule
• Drainage recommendation
• Soil nutrient recommendation

Farming method strategy I apply

Financial forecast I calculate

Expected Yield, Expected Revenue, Input Costs, Net Profit, ROI, 75/25 Model Targets.

Daily advisory

I generate dynamic recommendations based on Crop, Season, and Method.

19. My Data Models

What I’ve actually built (JSON files)

FARMER

{
  "id": "",
  "userId": "",
  "name": "",
  "phone": "",
  "email": ""
}

FARM

{
  "id": "",
  "farmerId": "",
  "farmName": "",
  "primaryCrop": "",
  "farmingMethod": "",
  "soilType": "",
  "waterSource": "",
  "landSize": 0
}

WIZARDPROGRESS

{
  "id": "",
  "userId": "",
  "currentStep": 1,
  "completedSteps": [],
  "stepData": {}
}

What I’ve planned for the future (PostgreSQL + Prisma)

• User
• Farm
• Field
• Crop
• CropCycle
• Task
• Inventory
• DiseaseReport
• IrrigationSchedule
• FertilizerApplication
• Harvest
• ExportCertificate
• Notification

20. My API Reference

21. My Land Conversion Engine

Location: lib/unitConverter.ts

Units I support: Decimal, Bigha, Katha

1 Bigha   = 33 Decimal
1 Decimal = 3.03 Katha

Where I use it: Wizard Step 7 (Land Measurement / Farm Details).

22. My Security Architecture

My planned upgrade: move to NextAuth.js with full RBAC as the platform matures (see §5.2 and §11).

23. My Performance Optimizations

The hero image LCP fix I made

The issue I ran into: Largest Contentful Paint (LCP) warnings, because my hero image sits above the fold.

How I fixed it:

loading="eager"

The result: improved perceived load speed, LCP warnings resolved, and I kept all the Next.js image optimization benefits.

The Next.js config updates I made

Remote image support (next.config.mjs):

images: {
  remotePatterns: [
    {
      hostname: "images.unsplash.com",
    },
  ],
}

Local network dev access:

allowedDevOrigins: ["192.168.56.1"]

This lets my dev resources load correctly when I access the app over my local network.

Validation results I got (at time of refactor)

My dev server (at time of refactor)

Local:   http://localhost:3000
Network: http://192.168.56.1:3000

24. My Developer Setup

# Install dependencies
npm install

# Run development server
npm run dev

# Type check
npx tsc --noEmit

# Production build
npm run build

# Start production server
npm start

25. My Current MVP User Journey

Landing Page
     │
     ▼
Sign Up
     │
     ▼
Verify Email
     │
     ▼
Sign In
     │
     ▼
Dashboard
     │
     ▼
Plant Management
     │
     ▼
Crop Selection
     │
     ▼
Farming Method Selection
     │
     ▼
11-Step Farm Wizard
     │
     ▼
Create Farm
     │
     ▼
Personalized Analytics Dashboard
     │
     ▼
Future ERP Modules

26. My Future Roadmap

Near-term, from my Banana Farm Setup / Product Development Roadmap

Long-term, from my Technical Documentation

Landing page — things I still want to do

• Extract Farm Setup into its own component.
• Separate Journey Timeline into reusable sections.
• Create dedicated Platform Features components.
• Isolate the AI Assistant panel.
• Move translations into dedicated locale files.
• Implement full Next.js internationalization support.
• Add animation and interaction enhancements.

27. Things I Still Need to Reconcile

Since this reference pulls together several of my own planning documents written at different project stages, a few inconsistencies crept in. I’m listing them here so I remember to resolve them against my live codebase:

1. Frontend/backend stack conflict: in my Banana Farm Setup planning doc I recommended React + Vite + Django + PostgreSQL, but my Technical Documentation and Landing Page Refactor notes confirm what I actually built is Next.js full-stack with a local JSON database. The Next.js approach is what’s actually running — the React/Vite/Django idea was an earlier proposal I ended up not using.
2. Auth provider conflict: my System Architecture diagram proposes NextAuth.js, but what I’ve actually built for authentication is a custom JWT + PBKDF2 + JSON file implementation. NextAuth.js is a planned future migration, not what’s running today.
3. Database conflict: my System Architecture diagram specifies Supabase PostgreSQL + Prisma, but my Technical Documentation and Project Structure confirm the MVP currently persists everything in local JSON files (data/*.json). Postgres/Prisma is the upgrade path I’ve planned for once the MVP validates the product.
4. Wizard step ordering conflict: my Technical Documentation and my Banana Farm Setup spec describe different step groupings for the 11-step wizard (see §15.1 vs §15.2). I need to confirm against components/wizard/steps/ which version I actually shipped.
5. Dashboard empty-state conflict: my Banana Farm Setup spec describes a genuinely empty state (“No active farms”), while my Technical Documentation’s Dashboard State 1 shows mock values (Active Farms: 2, Crops Growing: 2, Alerts: 3) instead. The mock-value version is what I’m actually running in the MVP, used for early testing/demo purposes.
6. Garbled Bengali strings: several Bengali-language UI strings (CTA labels, nav link labels, hero translation values) got corrupted somewhere during export from my original source documents, and I couldn’t reliably reconstruct them. I’ve flagged them inline rather than guessing — I’ll pull the real strings from my live source code when I formalize this documentation.