diff --git a/FLOW_DIAGRAM.md b/FLOW_DIAGRAM.md new file mode 100644 index 0000000..458e3b2 --- /dev/null +++ b/FLOW_DIAGRAM.md @@ -0,0 +1,287 @@ +# ๐ŸŒพ KrushiSaathi โ€” Application Flow Diagram + +## 1. High-Level Application Architecture + +```mermaid +flowchart TB + subgraph Client["Client (Browser)"] + UI["Next.js Frontend\n(React 19 + Tailwind CSS)"] + CTX["Context Providers\n(User / Yard / Lab / Navigation)"] + HOOKS["Custom Hooks\n(LiveAPI / MediaStream / Webcam)"] + end + + subgraph Server["Next.js API Routes"] + AUTH_API["Auth API\n(/api/auth/*)"] + USER_API["User API\n(/api/user/*)"] + YARDS_API["Yards API\n(/api/yards/*)"] + LABS_API["Labs API\n(/api/soil-agent/labs/*)"] + end + + subgraph External["External Services"] + FIREBASE["Firebase Firestore\n(Database)"] + GEMINI["Google Gemini API\n(AI Voice Assistant)"] + CLOUDINARY["Cloudinary\n(Image / PDF Storage)"] + GMAPS["Google Maps API\n(Lab Location)"] + end + + UI <--> CTX + CTX <--> HOOKS + UI -- "HTTP Requests" --> AUTH_API + UI -- "HTTP Requests" --> USER_API + UI -- "HTTP Requests" --> YARDS_API + UI -- "HTTP Requests" --> LABS_API + UI -- "WebSocket" --> GEMINI + UI --> GMAPS + + AUTH_API <--> FIREBASE + USER_API <--> FIREBASE + YARDS_API <--> FIREBASE + YARDS_API --> CLOUDINARY + LABS_API <--> FIREBASE +``` + +--- + +## 2. Authentication & Routing Flow + +```mermaid +flowchart TD + START([User visits any page]) --> MW{Middleware\nChecks JWT cookie} + + MW -- "No token &\npath โ‰  /login, /signup" --> LANDING[/landing page/] + MW -- "No token &\npath = /login or /signup" --> ALLOW_AUTH[Show Login / Signup] + MW -- "Has token" --> VERIFY{Verify JWT} + + VERIFY -- "Invalid token" --> LOGIN_PAGE[/login page/] + VERIFY -- "Valid token" --> ROLE{Check Role} + + ROLE -- "role = farmer &\npath = /login or /signup" --> FARMER_HOME["Redirect โ†’ / (Farmer Dashboard)"] + ROLE -- "role = farmer &\npath = /soil-agent" --> FARMER_HOME + ROLE -- "role = farmer &\nother paths" --> ALLOW_FARMER[Allow access] + + ROLE -- "role = soil-agent &\npath = /login or /signup" --> AGENT_HOME["Redirect โ†’ /soil-agent"] + ROLE -- "role = soil-agent &\npath โ‰  /soil-agent" --> AGENT_HOME + ROLE -- "role = soil-agent &\npath = /soil-agent" --> ALLOW_AGENT[Allow access] +``` + +--- + +## 3. User Registration (Signup) Flow + +```mermaid +flowchart TD + SIGNUP_PAGE([Signup Page]) --> ROLE_SELECT{Select Role} + + ROLE_SELECT -- "Farmer" --> FARMER_FORM["Fill Farmer Form\n(Name, Username, Password,\nAadhaar, Address, Passbook, Photo)"] + ROLE_SELECT -- "Soil Agent" --> AGENT_FORM["Fill Agent Form\n(Lab Name, Username, Password,\nAddress, Phone, Location)"] + + FARMER_FORM --> VALIDATE_F{Validate with Yup} + AGENT_FORM --> VALIDATE_A{Validate with Yup} + + VALIDATE_F -- "Invalid" --> FARMER_FORM + VALIDATE_A -- "Invalid" --> AGENT_FORM + + VALIDATE_F -- "Valid" --> UPLOAD_IMG["Upload Images\nto Cloudinary"] + VALIDATE_A -- "Valid" --> API_SIGNUP_A + + UPLOAD_IMG --> API_SIGNUP_F["POST /api/auth/signup\n(role = farmer)"] + API_SIGNUP_A["POST /api/auth/signup\n(role = soil-agent)"] + + API_SIGNUP_F --> HASH["Hash password\n(bcryptjs)"] + API_SIGNUP_A --> HASH + + HASH --> STORE["Store in\nFirebase Firestore"] + STORE --> JWT["Generate JWT\n(id + role)"] + JWT --> COOKIE["Set HTTP-only cookie\n(token + role)"] + COOKIE --> REDIRECT_F["Redirect โ†’ /\n(Farmer Dashboard)"] + COOKIE --> REDIRECT_A["Redirect โ†’ /soil-agent\n(Agent Dashboard)"] +``` + +--- + +## 4. Farmer Journey โ€” Complete Flow + +```mermaid +flowchart TD + LOGIN([Farmer Logs In]) --> DASH["๐Ÿ  Farmer Dashboard\n(Home)"] + + DASH --> F1["๐Ÿงช Soil Testing"] + DASH --> F2["๐ŸŽ™๏ธ Voice Assistant\n(Gemini AI)"] + DASH --> F3["๐Ÿ“ฐ News &\nMarket Updates"] + DASH --> F4["๐Ÿ’ฌ Help &\nSupport"] + DASH --> F5["โš™๏ธ Settings"] + + F1 --> HOW_TO{"Know how to\ncollect samples?"} + HOW_TO -- "No" --> GUIDE["/how-to\n(Collection Guide)"] + HOW_TO -- "Yes" --> REG_PAGE + + GUIDE --> REG_PAGE["/register-soil-sample\n(Select Testing Lab)"] + + REG_PAGE --> MAP["View Labs on\nGoogle Maps"] + MAP --> SELECT_LAB["Select a Lab"] + SELECT_LAB --> REG_FORM["/register-soil-sample/[labId]\n(Fill Sample Details)"] + REG_FORM --> YARD_NAME["Enter Yard Name\n& Sample Names"] + YARD_NAME --> SUBMIT["POST /api/yards\n(Create Yard)"] + SUBMIT --> TRACK_FORM["Download\nTracking Form"] + + TRACK_FORM --> PROGRESS["/test-progress/[yardId]\n(Monitor Status)"] + + PROGRESS --> STATUS{Sample Status?} + STATUS -- "Registered" --> WAIT1["โณ Waiting for\nlab to receive"] + STATUS -- "In Process" --> WAIT2["๐Ÿ”ฌ Lab is\ntesting sample"] + STATUS -- "Completed" --> VIEW_REPORT + + VIEW_REPORT["/view-report\n(All Reports List)"] + VIEW_REPORT --> REPORT["/results/[yardId]\n(Detailed Report)"] + + REPORT --> NUTRIENTS["๐Ÿ“Š Nutrient Charts\n(N, P, K, pH, EC, OC,\nFe, Mn, Zn, Cu, B, S)"] + REPORT --> SUGGESTIONS["๐Ÿ’ก AI-Generated\nSuggestions"] + REPORT --> PDF["๐Ÿ“„ Download\nPDF Report"] + + REPORT --> SMART_REC["/smart-recommendations\n(Crop Recommendations)"] + + F2 --> VOICE_CHAT["Real-time Voice Chat\nvia Google Gemini\nMultimodal Live API"] +``` + +--- + +## 5. Soil Agent Journey โ€” Complete Flow + +```mermaid +flowchart TD + AGENT_LOGIN([Soil Agent Logs In]) --> AGENT_DASH["๐Ÿงช Soil Agent Dashboard"] + + AGENT_DASH --> VIEW_FARMERS["๐Ÿ‘ฅ View Registered Farmers\n(GET /api/yards?soil-agent=labId)"] + AGENT_DASH --> ANALYTICS["๐Ÿ“Š Dashboard Analytics\n(Pending / In-Process / Completed)"] + + VIEW_FARMERS --> SELECT_YARD["Select a Yard\n(Farmer's Submission)"] + SELECT_YARD --> YARD_DETAIL["View Yard Details\n& Sample List"] + + YARD_DETAIL --> SAMPLE{Select a Sample} + + SAMPLE --> UPDATE_STATUS["Update Sample Status"] + UPDATE_STATUS --> S1["registered โ†’ in-process"] + UPDATE_STATUS --> S2["in-process โ†’ completed"] + + S2 --> INPUT_RESULTS["Input Test Results"] + INPUT_RESULTS --> MACRO["Macro Nutrients\n(N, P, K)"] + INPUT_RESULTS --> SECONDARY["Secondary Nutrients\n(S)"] + INPUT_RESULTS --> MICRO["Micro Nutrients\n(Fe, Mn, Zn, Cu, B)"] + INPUT_RESULTS --> PHYSICAL["Physical Parameters\n(pH, EC, OC)"] + + MACRO --> UPLOAD + SECONDARY --> UPLOAD + MICRO --> UPLOAD + PHYSICAL --> UPLOAD + + UPLOAD["Upload PDF Report\nto Cloudinary"] + UPLOAD --> SEND["PUT /api/yards/sendReport\n(Save Results + PDF URL)"] + SEND --> NOTIFY["โœ… Report Available\nfor Farmer"] +``` + +--- + +## 6. API Request Flow + +```mermaid +flowchart LR + subgraph Authentication + A1["POST /api/auth/signup"] --> DB1[(Firebase)] + A2["POST /api/auth/login"] --> DB1 + A3["GET /api/auth/logout"] --> CLEAR["Clear Cookies"] + end + + subgraph User + U1["GET /api/user"] --> DB2[(Firebase)] + U2["GET /api/user/checkAuth"] --> VERIFY_JWT["Verify JWT"] + end + + subgraph Yards + Y1["GET /api/yards\n(?farmer=id | ?soil-agent=id)"] --> DB3[(Firebase)] + Y2["POST /api/yards"] --> DB3 + Y3["GET /api/yards/[id]"] --> DB3 + Y4["PUT /api/yards/sendReport"] --> CLD["Cloudinary"] + Y4 --> DB3 + end + + subgraph Labs + L1["GET /api/soil-agent/labs"] --> DB4[(Firebase)] + L2["GET /api/soil-agent/labs/[id]"] --> DB4 + end +``` + +--- + +## 7. Data Flow โ€” Soil Sample Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> Registered : Farmer submits\nsoil sample + + Registered --> InProcess : Soil Agent receives\n& starts testing + + InProcess --> Completed : Agent uploads\nresults & PDF + + Completed --> ReportViewed : Farmer views\ndetailed report + + ReportViewed --> Recommendations : Farmer checks\ncrop suggestions + + Recommendations --> [*] + + state Registered { + [*] --> SampleCreated + SampleCreated --> YardStored : POST /api/yards + YardStored --> TrackingForm : Download tracking form + } + + state InProcess { + [*] --> StatusUpdated + StatusUpdated --> LabTesting : Lab analyzes nutrients + } + + state Completed { + [*] --> ResultsEntered + ResultsEntered --> PDFUploaded : Upload to Cloudinary + PDFUploaded --> ReportSaved : PUT /api/yards/sendReport + } +``` + +--- + +## 8. Voice Assistant (Gemini AI) Flow + +```mermaid +flowchart TD + USER([Farmer opens Voice Chat]) --> MIC["๐ŸŽค Capture Audio\n(MediaStream API)"] + MIC --> PROCESS["Audio Processing\n(AudioWorklet)"] + PROCESS --> STREAM["Stream to\nGemini Multimodal Live API\n(WebSocket)"] + STREAM --> GEMINI["๐Ÿค– Google Gemini\nProcesses Query"] + GEMINI --> RESPONSE["AI Response\n(Text + Audio)"] + RESPONSE --> AUDIO_OUT["๐Ÿ”Š Play Audio\nResponse"] + RESPONSE --> TEXT_OUT["๐Ÿ“ Display Text\nResponse"] + AUDIO_OUT --> USER + TEXT_OUT --> USER +``` + +--- + +## 9. End-to-End User Journey (Summary) + +```mermaid +flowchart LR + A["๐ŸŒ Landing Page"] --> B["๐Ÿ” Signup / Login"] + B --> C{Role?} + C -- Farmer --> D["๐Ÿ  Dashboard"] + C -- Soil Agent --> I["๐Ÿงช Agent Dashboard"] + + D --> E["๐Ÿ“ Select Lab\n& Register Sample"] + E --> F["๐Ÿ“ฆ Track\nProgress"] + F --> G["๐Ÿ“Š View Report\n& Charts"] + G --> H["๐ŸŒฑ Smart Crop\nRecommendations"] + D --> J["๐ŸŽ™๏ธ Voice\nAssistant"] + + I --> K["๐Ÿ‘ฅ View\nFarmers"] + K --> L["๐Ÿ”ฌ Test\nSamples"] + L --> M["๐Ÿ“„ Upload\nResults"] + M -->|Report available| G +``` diff --git a/README.md b/README.md index f26ec2e..82f9db3 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,12 @@ You can try the working prototype at: --- +## ๐Ÿ“Š Flow Diagram + +For a comprehensive visual overview of the application architecture, authentication flow, user journeys, and API interactions, see the [Flow Diagram](FLOW_DIAGRAM.md). + +--- + ## ๐Ÿ“„ Project Structure ```