Sprint 1 - JuanJoseBotero/Merko GitHub Wiki

Table of Contents

1. Business Plan

1.1 Executive Abstract

1.1.1. Business Description

Our project consists of an AI-powered web platform that allows companies, consultants, and freelancers to perform market analysis quickly, easily, and visually. The value proposition focuses on automating market research using predefined prompt templates, where the user enters partial information and the system generates a structured analysis accompanied by interactive graphics. The problem we solve is the lack of accessibility and speed in market analysis: currently, these tasks require advanced knowledge or expensive and complex tools.

1.1.2. Founders / Management team

The team, consisting of four developers, has experience in different areas:

  • Developing modern web applications using advanced technologies such as React.
  • Integrating and using artificial intelligence APIs (e.g., OpenAI).
  • Web scraping techniques for obtaining and processing market data.
  • Managing technology projects focused on innovative digital solutions.

The skills are complementary, combining technical expertise, user experience design, and strategic market orientation.

1.1.3. Product / Services

The main service is the AI-powered market analysis platform, which includes:

  • Predefined analysis templates: Import Analysis, Demand Analysis, Growth Opportunities, Customer Analysis, Competitive Analysis, Financial Analysis.
  • Visualization of results using bar, pie, and line charts integrated into an intuitive interface with Material UI and others libraries.
  • Flexible customization for different industries and company sizes.

The innovation lies in its simplicity and speed of use, users do not need technical knowledge to obtain useful insights, which sets it apart from traditional Business Intelligence tools.

1.1.4. Target Market

The target market is mainly composed of:

  • Entrepreneurs and startups that need to validate business ideas quickly and economically.
  • Small and medium-sized enterprises (SMEs) that require accessible information to make strategic decisions without relying on external consultants.
  • Marketing and consulting agencies looking for an agile tool to complement their services.
  • Big companies and corporations that can use the platform as an internal support tool, allowing their teams to obtain quick, visual analyses before conducting more in-depth research or large-scale projects.

Strengths: accessibility, ease of use, low cost compared to traditional tools.

Weaknesses: compared to large-scale solutions (e.g., SEMrush, Power BI), the initial scope is more limited, although it offers greater agility and customization.

1.1.5. Competitors

The main competitors are:

  • Market analysis tools (SEMrush, Statista, Nielsen).
  • BI platforms and dashboards (Power BI, Tableau).
  • Traditional market consulting firms.

Differentiation is achieved through:

  • AI with specific templates that simplify the process.
  • Affordable cost.
  • Immediate and visual results without a technical learning curve.

1.1.6. Short and Large Term Objectives

Short term (6-12 months):

  • Launch a minimum viable version with 5–6 types of analysis.
  • Attract first beta customers (SMEs and freelancers).
  • Adjust the platform based on user feedback.

Long term (2-5 years):

  • Expand the range of analyses with predictive models.
  • Scale the platform regionally and internationally.
  • Position ourself as a leader in agile market analysis with AI.

1.2 Business details

1.2.1 History and Background

The application was born from the natural drive of companies to maximize their profits, with market analysis being one of the most effective strategies to broaden their outlook and identify new opportunities. It was created in response to the lack of a platform capable of centralizing and processing information in a simpler, more visual, and efficient wayβ€”avoiding fragmented studies and the overload of irrelevant data. At the same time, it reflects the need to adopt emerging technologies, such as artificial intelligence, to foster business evolution and maintain a competitive edge in a constantly changing environment.

The most significant milestones in the development of the application include the first steps toward a deep understanding of how Large Language Models (LLMs) work, discovering ways to integrate them and process their outputs, and tailoring them to specific topics while ensuring strict adherence to rules. Another key milestone was the design of a natural and intuitive user experience, allowing even non-technical users to fully leverage the benefits offered by the application.

1.2.2 Mission and Vision

Mission: Our mission is to transform market information analysis into clear, easy-to-understand visual insights. We aim to guide users through intuitive prompts, enabling even non-experts to interpret the results. By integrating cutting-edge techniques and technologies, we enhance efficiency so businesses can focus their time on innovation and growth.

Vision: Our vision is to become as an innovation platform that exploit all the potencial of AI-driven market analysis, recognized for simplifying complex data and transforming it into actionable insights. We strive to be an essential tool for companies aiming to remain competitive, agile, and innovation-driven in an ever-changing global landscape.

1.2.3 Values

At Merko, we believe our principles should be reflected both in our technology and in the user experience. Our core values are:

  • Innovation: We embrace and develop cutting-edge technologies to transform the way information is analyzed.

  • Clarity: We turn complex data into simple and understandable visual insights.

  • Accessibility: We design tools that can be used by anyone, regardless of technical expertise.

  • Trust: We ensure transparency and consistency in data processing and presentation.

Shared Growth: We foster the success of the businesses and professionals who rely on our platform.

1.3 Market Analysis

1.3.1 Market Research

The platform is developed from the identification of a clear need: democratizing access to reliable and fast market analysis.

  • Reliable and updated sources are used (public databases, external APIs, consumption trends, data obtained via web scraping).
  • The research reflects the breadth of the market, considering entrepreneurs, SMEs, and large corporations.

1.3.2 Market Segmentation

The market is segmented into three main groups:

  • Startups and entrepreneurs β†’ need quick validation of business ideas.
  • SMEs and consulting/marketing agencies β†’ seek accessible and visual information for strategic decisions.
  • Large companies / corporations β†’ use the tool as an agile support system in early research phases or as a complement to existing BI systems.

Each segment has specific needs: speed, accessibility, customization, and cost reduction in market research.

1.3.3 Target Customers

Our target customers are companies and professionals who need to accelerate strategic decision-making based on data.

  • Startups β†’ gain immediate insights without investing in expensive consultancies.
  • SMEs β†’ improve competitiveness with accessible and visual analysis.
  • Large enterprises β†’ provide internal teams with an agile tool to explore markets and generate hypotheses before large-scale studies.

The platform generates relevant insights about behaviors, preferences, and consumption trends, customizable to each industry through AI prompt templates.

1.3.4 Competitors Analysis

The competitive landscape shows that companies currently rely on established tools and services such as SEMrush, Statista, and Nielsen for market analysis, or on business intelligence platforms like Power BI and Tableau. In addition, many organizations still work with traditional consulting firms to access detailed reports and strategic insights.

Competitors Strenghts: These competitors excel in providing comprehensive data and advanced features

Weaknesses compared to our proposal: They face limitations in terms of cost, complexity, and accessibility

Our competitive advantage lies in offering an agile, flexible, and accessible service that adapts to SMEs as well as large corporations.

1.4 Service

1.4.1 Service description

Merko is a web application powered by an AI agent specialized in market analysis. The platform enables users to generate dynamic, visual dashboards through predefined and customizable prompts. Its main features include:

  • Centralization of information from multiple sources (AI, web scraping, APIs).

  • Presentation of results through intuitive charts and visualizations.

  • Simple, user-friendly interaction designed for both technical and non-technical users.

1.4.2 Value Proposition

Merko's value proposition focuses on transforming the complexity of market analysis into clear, visual, and actionable information. Unlike traditional tools that require advanced technical knowledge or multiple platforms, Merko integrates AI, web scraping, API connectivity, and visualization in one place, giving companies the ability to quickly understand and act on market changes.

1.4.3 Service Lifecycle

  • Discovery / Sign-up: User finds the platform and creates an account.

  • Onboarding / Setup: Guided by predefined prompts, the user configures data sources (AI, web scraping, APIs).

  • Active Use: User builds customized dashboards and interprets consolidated insights for decision-making.

  • Support / Updates: Access to customer support and continuous feature improvements.

  • Retention / Scaling: User adopts Merko as a daily tool and integrates more advanced features.

1.5 Implementation

1.5.1

The implementation plan for Merko is divided into realistic phases to ensure structured and progressive development:

Phase 1 – Design & Prototype (0–5 weeks): 12th August - 9th September

  • UI/UX design.
  • Initial prototype with core AI functions.
  • LLM integration with customizable prompts.
  • Testing

Phase 2 – Development & Internal Testing (5-8 weeks): 9th Sempember - 30th September

  • Creation of basic dashboards.
  • Web Scrapping Integration
  • Technical testing and bug fixing.

Phase 3 – Last Details and Pilot Testing (8-12 weeks): 30th September - 28th October

  • Beta release.
  • Collect feedback and improve usability.
  • Launch the Web App

1.5.2 Key Milestones

  • Functional prototype completed (Week 5).
  • Basic dashboards, Web Scrapping and APIs integrated (Week 8).
  • Pilot testing and Launch (Week 12).

1.5.3 Required Resources

To ensure successful implementation, the following resources are required:

Human resources:

  • Development team (frontend, backend, AI, Architecture, Tester): Essential to build the application, ensure proper integration of language models, and maintain a scalable and secure platform.
  • UX/UI developers: Ensure the app is intuitive, visually appealing, and easy to use, enabling adoption even by non-technical users.

Technological resources:

  • Cloud infrastructure (GCP/Azure, server as Django REST, APIs): Essential for ensuring availability, speed, and scalability as the user base grows, as well as being responsible for providing information through connections with APIs or LLM models.
  • Monitoring and analytics tools: Required to assess system performance, detect issues, and continuously improve user experience.
  • Licenses and frameworks: Provide an efficient and secure programming environment, ensuring compatibility with state-of-the-art AI technologies.

Financial resources:

  • Investment in IA Agent: Provides high-quality, consistent answers.

Each resource is essential to deliver a robust, scalable, and competitive product.

2. Test Cases (TC)

Test Case 1: Basic navigation (US01: Prompts Catalog).

  • Given: The user is on the Home page.
  • When: The user clicks the Catalog button.
  • Then: The system displays the available categories with their respective description.
  • When: The user clicks the View Prompts button.
  • Then: The system displays the prompts associated with that category.

Evidence:

File location:

  • Merko/Backend/catalog/tests/test_categories.py
  • Merko/Backend/catalog/tests/test_prompts.py

Execution:

Bug:

  • Title: Migration conflict when running tests with pytest-django.
  • Description: When running tests with pytest, an error occurs during the test database setup phase. The traceback indicates a migration conflict in the catalog app.
  • Solution: python manage.py makemigrations --merge

Test Case 2: Selection and editing of a prompt (US02: Message Parameterization).

  • Given: The user sees the list of prompts in a category.
  • When: The user selects a prompt.
  • Then: The system loads the prompt with its editable fields in text boxes.
  • When: The user modifies at least one field.
  • Then: The system reflects the changes in the state (React) without errors.

Test Case 3: Successful request to the OpenAI API (US03: Analysis with AI).

  • Given: The user edits a prompt.
  • When: The user clicks Send.
  • Then: The frontend sends the edited prompt to the backend (DRF).
  • And: The backend sends it to the OpenAI API.
  • And: The system receives a valid JSON response.
  • Then: The frontend displays the structured JSON correctly.

Evidence:

File location:

  • Merko/Backend/analysis/tests/test_openai.py::test_send_prompt_success

Execution:

Test Case 4: API error handling (US03: Analysis with AI).

  • Given: The user edits a prompt.
  • When: The user clicks Send.
  • And: The OpenAI API responds with an error (e.g., token limit, invalid API key, timeout).
  • Then: The backend returns a controlled error to the frontend.

Evidence:

File location:

  • Merko/Backend/analysis/tests/test_openai.py::test_send_empty_prompt

Execution:

3. Software quality

3.1. Naming conventions

For Django (Backend), the official PEP8 style guide was used. To ensure consistency, we integrated:

  • flake8: static-level tool that detects style errors and possible bugs.
  • black: a strict code formatter that applies automatic corrections, focusing on aesthetics and consistency rather than error detection.

References:

For Frontend (React + TypeScript), the tools used were:

  • ESLint: static-level tool that enforces coding standards and best practices.
  • Prettier: opinionated code formatter, ensuring consistent style across the codebase.

These are standard tools widely adopted in the TypeScript + React ecosystem, which justifies their selection.

References:

3.2. Static code analysis

Static analysis tools:

  • flake8 was chosen for its ability to detect style issues and potential bugs.
  • ESLint to ensure code quality and style.

Formatter tools:

  • black was chosen for its strict automatic formatting, which saves time during code reviews.
  • prettier to ensure code quality and style.
Tool Type Detects Errors Applies Automatic Fixes Level
flake8 Linter Yes (variables, imports, syntax, style) No (only warns) Static
black Formatter No (does not analyze logic) Yes (rewrites code to Black style) Aesthetic
ESLint Linter Yes (syntax, unused vars, best practices) No (warns, but can be combined w/ fixes) Static
Prettier Formatter No (does not check logic or syntax) Yes (rewrites code to consistent style) Aesthetic

Additionally, pre-commit hooks were set up so that every commit is automatically checked and formatted, guaranteeing that the project always follows established standards. References:

To use these tools follow the steps:

  1. Install dependencies
pip install -r requirements.txt
  1. Configure .flake8 file
[flake8]
max-line-length = 88
extend-ignore = E203, W503
  1. Configure .pre-commit-config.yaml file
repos:
  - repo: https://github.com/psf/black
    rev: 25.1.0
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/flake8
    rev: 7.1.0
    hooks:
      - id: flake8
  1. Install and enable pre-commit
pip install pre-commit
pre-commit install
  1. Install dependencies (Front)
npm install
  1. Configure eslint.config.js file
import js from "@eslint/js";
import globals from "globals";
import reactHooks from "eslint-plugin-react-hooks";
import reactRefresh from "eslint-plugin-react-refresh";
import tseslint from "typescript-eslint";
import prettier from "eslint-plugin-prettier";
import configPrettier from "eslint-config-prettier";
import { globalIgnores } from "eslint/config";

export default tseslint.config([
  globalIgnores(["dist"]),
  {
    files: ["**/*.{ts,tsx}"],
    extends: [
      js.configs.recommended,
      tseslint.configs.recommended,
      reactHooks.configs["recommended-latest"],
      reactRefresh.configs.vite,
      configPrettier,
    ],
    plugins: {
      prettier,
    },
    rules: {
      "prettier/prettier": "warn",
    },
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
    },
  },
]);
  1. Test every tool
flake8 .
black .
npx eslint .
npx prettier --check .
npx prettier --write .

Below are some examples of how tools help achieve standards. black flakecatalog pruebaprecommit

3.3. Branching Strategy in Merko

Instead of using heavy strategies like GitFlow, the team adopted a lightweight and agile approach.
Each new feature, fix, or task is developed in a short-lived branch, with a prefix indicating the type of work. Main prefixes:

  • feat/ β†’ new functionalities
    Example: feat/message_parameterization
  • refactor/ β†’ restructuring or improving existing code without changing behavior
    Example: refactor/api_calls
  • style/ β†’ formatting changes, variable renaming, indentation, or CSS tweaks that do not affect logic
    Example: style/navbar_css
  • chore/ β†’ maintenance tasks (dependencies, configs, CI/CD, scripts)
    Example: chore/software_quality_tools This approach keeps the workflow simple, avoids large and complex branches, and facilitates faster integration into the main codebase.

4. Backlog and ceremony

4.1 Backlog

4.2 Evidence of the ceremonies

We held several team meetings to share progress and explain the features to others so that they could integrate these features with their own. evidencias1p2

We also had a meeting with the stakeholder to review progress and receive feedback on the website. preubaa

5. Presentation

  • See the presentation here