System Requirements Document (SRD)

Project Name: spicy-shopkeepers

1. Introduction

The spicy-shopkeepers project aims to develop a B2B wholesale mobile application tailored for shopkeepers (retailers) to order products in bulk directly from wholesalers. This initiative is part of Ahmad Raza's business "Online Baqala," based in Pakistan, and is designed to simplify bulk ordering for shopkeepers while ensuring ease of use for non-tech-savvy users.

The application will feature a clean, modern UI with a green theme to align with grocery branding and will include essential functionalities such as user authentication, product catalog management, bulk ordering, and payment options. A web-based admin panel will be developed for easier management, with potential consideration for a mobile-friendly admin panel in the future.

2. System Overview

The spicy-shopkeepers application will serve as a wholesale ordering platform for shopkeepers, enabling them to browse products, place bulk orders, and manage their order history. The system will consist of:

1. A mobile application for shopkeepers to access the product catalog, place orders, and receive notifications.
2. A web-based admin panel for wholesalers to manage products, users, and orders efficiently.
3. Backend services to handle authentication, database management, and notifications.

The system will prioritize simplicity and speed, ensuring shopkeepers can navigate and use the app with minimal technical expertise.

3. Functional Requirements

Shopkeeper Features

• As a Shopkeeper, I should be able to register using my phone number, shop name, owner name, and address.
• As a Shopkeeper, I should receive an OTP for login and require admin approval before activation.
• As a Shopkeeper, I should be able to browse products categorized by type (e.g., grocery items).
• As a Shopkeeper, I should see product details, including name, image, wholesale price, minimum order quantity (MOQ), and stock availability.
• As a Shopkeeper, I should be able to select quantities in bulk (e.g., cartons) and see auto price calculations.
• As a Shopkeeper, I should be able to add items to the cart and place orders.
• As a Shopkeeper, I should be able to view my order history and track order statuses (Pending, Confirmed, Delivered).
• As a Shopkeeper, I should receive notifications for order confirmations and status updates.

Admin Features

• As an Admin, I should be able to add, edit, and delete products.
• As an Admin, I should be able to manage users, including approving or rejecting registrations.
• As an Admin, I should be able to view and update order statuses.
• As an Admin, I should have access to a web-based admin panel for easier management.
• As an Admin, I should have the option to explore a mobile-friendly admin panel for on-the-go management in the future.

4. User Personas

Shopkeeper (Retailer)

• Description: Small business owners who run retail shops and need to order products in bulk from wholesalers.
• Technical Expertise: Low; prefers simple and intuitive interfaces.
• Goals: Efficiently browse products, place bulk orders, and track order statuses.

Admin (Wholesaler)

• Description: Business owners or managers responsible for managing product catalogs, user registrations, and orders.
• Technical Expertise: Moderate; comfortable using web-based tools for management.
• Goals: Streamline product and order management, approve user registrations, and ensure smooth operations.

5. Visuals Colors and Theme

Color Palette

The spicy-shopkeepers app will feature a unique color palette inspired by grocery branding and the vibrant energy of wholesale markets:

• Background: #F5F9F6 (Soft Mint Green)
• Surface: #E8F1E9 (Light Green Tint)
• Text: #2E4A2F (Deep Forest Green)
• Accent: #FFD700 (Golden Yellow for highlights and buttons)
• Muted Tones: #A3B4A5 (Muted Sage Green for secondary elements)

6. Signature Design Concept

Floating Market Experience

The homepage of the spicy-shopkeepers app will feature an interactive "Floating Market" design. Users will be greeted with a dynamic visual of a bustling wholesale market, where product categories are represented as floating stalls.

• Animations: Stalls gently sway as if floating on water, creating a calming yet engaging effect.
• Interactions: Users can tap on stalls to "enter" a category, with smooth transitions that mimic walking into a shop.
• Micro-interactions: Products within each stall will have hover effects, such as slight zoom-ins and glowing borders.
• Color Shifts: The background subtly transitions from morning hues (soft greens and yellows) to evening tones (deeper greens and golden accents) based on the time of day.

This design will make the app instantly memorable and provide a delightful user experience, especially for shopkeepers who appreciate visual simplicity and charm.

7. Non-Functional Requirements

• The app must be responsive and optimized for low-end Android devices commonly used by shopkeepers.
• The system should support high concurrency to handle multiple users browsing and ordering simultaneously.
• Notifications should be delivered promptly to ensure users are updated in real-time.
• The admin panel should be secure, with role-based access control.

8. Tech Stack

Frontend

• Mobile App: Flutter
• Admin Panel: React

Backend

• Language: Python
• Framework: FastAPI

Database

• RDBMS: MySQL (with Alembic for migrations)

AI Tools

• LLM Routing: Litellm
• Image Generation: Google Nano Banana

Orchestration

• Local: Docker, docker-compose
• Server-side: Kubernetes

9. Assumptions and Constraints

Assumptions

• Shopkeepers will primarily use Android devices.
• Admins will prefer web-based tools for management tasks.
• Users will have access to stable internet connections for app usage.

Constraints

• The app must be lightweight to ensure compatibility with low-end devices.
• Payment methods will initially be limited to Cash on Delivery and Bank Transfer.

10. Glossary

• B2B: Business-to-Business; refers to transactions between businesses, such as wholesalers and retailers.
• MOQ: Minimum Order Quantity; the smallest quantity of a product that can be ordered.
• OTP: One-Time Password; a secure method for user authentication.
• Admin Panel: A web-based interface for managing products, users, and orders.