System Requirements Document (SRD)

Project Name: deep-project

1. Introduction

Welcome to the System Requirements Document (SRD) for deep-project, a marketplace platform designed to list agencies and provide updated, accurate data about their profiles. This document outlines the requirements for developing an AI agent that automates the process of analyzing agency profiles, visiting their websites, extracting social media links, and updating ratings from Google Reviews, Facebook Reviews, and Clutch Reviews.

Kuldeep IT, based in India, envisions this project as a solution to streamline agency data management and ensure the marketplace remains reliable and user-friendly.

2. System Overview

The deep-project AI agent will:

1. Analyze each row in an Excel sheet containing agency details.
2. Dynamically create columns for social media links and ratings.
3. Visit the agency's website to extract social media links (LinkedIn, Facebook, Clutch, etc.).
4. Prioritize collecting ratings in the following order: Google Reviews → Facebook Reviews → Clutch Reviews.
5. Update the Excel sheet with the respective ratings in newly created columns.
6. Handle cases where no ratings are found by leaving cells blank.

This system will automate the tedious process of manually updating agency profiles, ensuring accuracy and efficiency.

3. Functional Requirements

Story Points:

• As a User, I should be able to upload an Excel sheet containing agency details.
• As an AI Agent, I should dynamically create columns for social media links and ratings in the Excel sheet.
• As an AI Agent, I should visit each agency's website from the Excel sheet and extract social media links.
• As an AI Agent, I should prioritize collecting ratings in this order: Google Reviews → Facebook Reviews → Clutch Reviews.
• As an AI Agent, I should update the Excel sheet with extracted ratings in respective columns.
• As an AI Agent, I should handle cases where no ratings are found by leaving the cell blank.

4. User Personas

1. Admin

• Role: Manages the marketplace and oversees agency listings.
• Needs: Accurate and updated agency profiles, automated data collection, and clean Excel sheets.

2. Agency Representative

• Role: Represents an agency listed on the marketplace.
• Needs: Ensure their profile is accurately represented with updated ratings and links.

3. Guest User

• Role: Browses the marketplace to find agencies.
• Needs: Reliable and up-to-date information about agencies.

5. Visuals Colors and Theme

Color Palette for deep-project:

• Background: #F5F5F5 (Soft Gray)
• Surface: #FFFFFF (Pure White)
• Text: #333333 (Deep Charcoal)
• Accent: #0078D7 (Vivid Blue)
• Muted Tones: #B0BEC5 (Light Steel Gray)

This palette reflects professionalism, clarity, and trustworthiness, aligning with the marketplace's purpose.

6. Signature Design Concept

Concept: Interactive Data Dashboard with AI Insights

The homepage of deep-project will feature an Interactive Data Dashboard that visually represents the AI agent's activity in real-time.

Key Features:

1. Dynamic Agency Map: A visual map where agencies are represented as interactive nodes. Clicking a node reveals the agency's profile, ratings, and social media links.
2. AI Activity Feed: A live feed showing the AI agent's progress as it updates ratings and extracts links. Micro-interactions like spinning icons and progress bars will make the feed engaging.
3. Rating Heatmap: A heatmap that visually displays the distribution of ratings across agencies, color-coded for quick insights.
4. Hover Animations: Smooth hover effects on agency nodes and dashboard elements to enhance user experience.
5. Theme Transitions: Subtle color shifts in the dashboard based on the time of day (e.g., cooler tones in the evening).

This design concept ensures the platform is visually captivating while emphasizing transparency and the AI agent's efficiency.

7. Non-Functional Requirements

• The system should process Excel sheets with up to 10,000 rows efficiently.
• The AI agent should extract data within 5 seconds per row.
• The system should handle missing or incomplete data gracefully without errors.
• The platform should be responsive and accessible across devices.
• The system must comply with data privacy regulations in India.

8. Tech Stack

Frontend:

• React for Web

Backend:

• Python
• FastAPI

Database:

• MySQL (preferred for structured data)
• Alembic for migrations

AI Models:

• GPT 5.4 for user-friendly responses
• Claude 4.6 Opas for academic or coding work

AI Tools:

• Litellm for LLM Routing
• Langchain

Local Orchestration:

• Docker
• docker-compose

Server-Side Orchestration:

• Kubernetes

9. Assumptions and Constraints

Assumptions:

• Agencies have websites with accessible social media links.
• Ratings are publicly available on Google, Facebook, and Clutch.
• The Excel sheet contains valid URLs for agency websites.

Constraints:

• The AI agent's functionality depends on the availability of internet access.
• The system must handle cases where websites or social media links are inaccessible.

10. Glossary

• AI Agent: A software component that automates data extraction and updates.
• Excel Sheet: A spreadsheet containing agency details, including URLs.
• Social Media Links: URLs to agency profiles on platforms like LinkedIn, Facebook, and Clutch.
• Ratings: Scores or reviews extracted from Google, Facebook, and Clutch.
• Heatmap: A graphical representation of data where values are depicted by color.