# issu321/marketmind-intelegence-ai-system-based architecture

> Architecture diagram of the GitHub repository issu321/marketmind-intelegence-ai-system-based, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/issu321/marketmind-intelegence-ai-system-based
- Repository: https://github.com/issu321/marketmind-intelegence-ai-system-based

## Overview

1. **Overall shape**
   - This is a **single-process Flask monolith** for market intelligence and forecasting, not a distributed system.
   - The application is server-rendered: Flask routes in `app.py` select HTML templates under `templates/`, and static assets live under `static/`.

2. **Core runtime boundary**
   - `app.py` is the main entry point and web server.
   - The app listens on port 5000 and is configured for local Docker deployment (`sdk: docker`, `app_port: 5000`).
   - The repo includes a prebuilt SQLite database at `instance/marketmind.db`, which suggests the app boots with persisted state rather than external infrastructure.

3. **Primary business subsystems**
   - The functionality is split into domain-focused modules:
     - `predictor.py` for forecasting and model selection
     - `analyzer.py` for data analysis / consumer intelligence
     - `intelligence.py` for competitor intelligence
     - `utils.py` for shared helpers
   - These modules are the main computation boundary between web request handling and analytics logic.

4. **Data ingestion and dataset lifecycle**
   - Datasets are a first-class input: users can upload CSVs through the datasets area, and uploaded files are stored in `uploads/`.
   - Example data is bundled in `Example-Datasets/`, including a dataset guide and a sample sales forecast CSV.
   - The dataset workflow likely follows: upload/import → persist file → register metadata in SQLite → analyze/forecast → display results in templates.

5. **Persistence layer**
   - `database/models.py` contains SQLAlchemy ORM models; the database is SQLite, as described in the README and reinforced by `instance/marketmind.db`.
   - The persistence boundary appears to cover application state such as users, datasets, activity logs, login history, and possibly generated reports.
   - This is a local embedded database architecture, not a remote DB service.

6. **Authentication and administration**
   - The app supports registration, login, password management, role-based access, activity logging, and login history.
   - Admin views live under `templates/admin/`, indicating a separate administrative UI surface for user and database oversight.
   - This creates a clear separation between end-user analytics flows and privileged operational flows.

7. **Analytical capabilities**
   - Forecasting is the most compute-heavy subsystem and supports multiple ML models, auto-selection, backtesting, and confidence intervals.
   - Competitor intelligence computes scoring, SWOT-style insights, and market concentration metrics.
   - Consumer intelligence handles sentiment/emotion/topic extraction.
   - Opportunity detection and scenario simulation are additional analytical pipelines, each likely invoked from its own Flask route and rendered into a dedicated page.

8. **Presentation layer**
   - The UI is organized by domain in templates such as `forecasting/`, `competitors/`, `consumer/`, `opportunities/`, `simulation/`, `executive/`, `reports/`, `visualizations/`, and `search/`.
   - `templates/base.html` provides the shared layout, while `templates/landing.html`, `templates/dashboard.html`, and role-specific pages form the main navigation surfaces.
   - This strongly suggests a multi-page application with page-level workflows rather than a single-page front end.

9. **Reporting and exports**
   - Reports are a distinct subsystem with templates under `templates/reports/`, including a report template and view pages.
   - The README indicates export formats such as PDF, HTML, CSV, and JSON, so reporting likely acts as a downstream consumer of analysis outputs.
   - Reports bridge analytics results and business presentation, probably reusing data from forecasts, intelligence, and executive summaries.

10. **Visualization pipeline**
   - Visualizations are separated into their own route/template area, with Plotly implied by the README.
   - Charts are likely generated from analysis outputs and dataset summaries, then embedded into server-rendered pages.
   - This is an important boundary: analytics modules produce results, while the visualization layer turns those results into interactive charts.

11. **Search and executive aggregation**
   - `templates/search/` suggests a cross-domain lookup surface over datasets, insights, reports, or entities.
   - The executive dashboard consolidates outputs from multiple subsystems into a higher-level KPI view.
   - In architecture terms, this is the aggregation layer that sits above forecasting, intelligence, and consumer analysis.

12. **Operational artifacts**
   - `uploads/` contains persisted uploaded CSVs, while `instance/marketmind.db` stores application state.
   - `Example-Datasets/` is documentation and seed data for users to understand supported inputs.
   - These folders are part of the app’s local runtime state and should be shown in any diagram as file-based storage alongside the SQLite database.

13. **Technology profile**
   - The stack is Python 3.11+, Flask, SQLAlchemy, pandas/NumPy/SciPy, scikit-learn plus XGBoost/LightGBM/CatBoost, Plotly, and NLP tooling such as NLTK and TextBlob.
   - These libraries matter architecturally because the app is a hybrid of web UI, ML inference/training, statistical analysis, and text analytics inside one backend.

14. **Key architectural takeaway**
   - The cleanest diagram is: **browser → Flask routes in `app.py` → domain modules (`predictor`, `analyzer`, `intelligence`) → SQLite / file storage → rendered templates**.
   - Everything else is a domain-specific surface on top of that core flow, with admin/auth and reporting as supporting subsystems.

Main entry points: [`app.py`](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/app.py) (Flask App), [`database/models.py`](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/database/models.py) (ORM Models), [`templates/competitors/index.html`](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/competitors/index.html) (Insight Pages), [`analyzer.py`](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/analyzer.py) (Analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser(("Browser<br/>client"))
  node_app["Flask App<br/>web entrypoint<br/>[app.py]"]
end

subgraph group_domain["Domain Logic"]
  node_predictor["Predictor<br/>forecasting engine<br/>[predictor.py]"]
  node_analyzer["Analyzer<br/>analysis engine<br/>[analyzer.py]"]
  node_intelligence["Intelligence<br/>competitor engine<br/>[intelligence.py]"]
  node_utils["Utils<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_data["Data & Persistence"]
  node_models[("ORM Models<br/>sqlalchemy models<br/>[models.py]")]
  node_sqlite[("Market DB<br/>sqlite store<br/>[marketmind.db]")]
  node_uploads["Uploads<br/>file store"]
  node_examples["Example Data<br/>seed files"]
end

subgraph group_ui["Presentation"]
  node_base["Base Layout<br/>shared template<br/>[base.html]"]
  node_dashboard["Dashboard<br/>home view<br/>[dashboard.html]"]
  node_forecast_ui["Forecasting UI<br/>workflow pages<br/>[index.html]"]
  node_intel_ui["Insight Pages<br/>workflow pages<br/>[index.html]"]
  node_reports_ui["Reports UI<br/>report pages<br/>[index.html]"]
  node_visuals_ui["Visuals UI<br/>chart pages<br/>[index.html]"]
  node_search_ui["Search UI<br/>lookup pages<br/>[index.html]"]
end

subgraph group_ops["Operations"]
  node_admin_ui["Admin UI<br/>admin pages<br/>[dashboard.html]"]
  node_auth_ui["Auth UI<br/>account pages<br/>[login.html]"]
end

node_browser -->|"HTTP requests"| node_app
node_app -->|"forecasting"| node_predictor
node_app -->|"analysis"| node_analyzer
node_app -->|"competitor intel"| node_intelligence
node_app -->|"helpers"| node_utils
node_app -->|"persistence layer"| node_models
node_models -->|"reads/writes"| node_sqlite
node_app -->|"dataset upload"| node_uploads
node_app -->|"seed data"| node_examples
node_app -->|"renders"| node_base
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_forecast_ui
node_app -->|"renders"| node_intel_ui
node_app -->|"renders"| node_reports_ui
node_app -->|"renders"| node_visuals_ui
node_app -->|"renders"| node_search_ui
node_app -->|"renders"| node_admin_ui
node_app -->|"renders"| node_auth_ui
node_forecast_ui -->|"drives"| node_predictor
node_intel_ui -->|"drives"| node_analyzer
node_intel_ui -->|"drives"| node_intelligence
node_reports_ui -->|"summarizes"| node_models
node_visuals_ui -->|"charts"| node_analyzer
node_admin_ui -->|"administers"| node_models
node_search_ui -->|"queries"| node_models

click node_app "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/app.py"
click node_predictor "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/predictor.py"
click node_analyzer "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/analyzer.py"
click node_intelligence "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/intelligence.py"
click node_utils "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/utils.py"
click node_models "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/database/models.py"
click node_sqlite "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/instance/marketmind.db"
click node_uploads "https://github.com/issu321/marketmind-intelegence-ai-system-based/tree/main/uploads"
click node_examples "https://github.com/issu321/marketmind-intelegence-ai-system-based/tree/main/Example-Datasets"
click node_base "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/base.html"
click node_dashboard "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/dashboard.html"
click node_forecast_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/forecasting/index.html"
click node_intel_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/competitors/index.html"
click node_reports_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/reports/index.html"
click node_visuals_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/visualizations/index.html"
click node_search_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/search/index.html"
click node_admin_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/admin/dashboard.html"
click node_auth_ui "https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/auth/login.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_app toneBlue
class node_predictor,node_analyzer,node_intelligence,node_utils toneAmber
class node_models,node_sqlite,node_uploads,node_examples toneMint
class node_base,node_dashboard,node_forecast_ui,node_intel_ui,node_reports_ui,node_visuals_ui,node_search_ui toneRose
class node_admin_ui,node_auth_ui toneIndigo
```

## Components

### Runtime

Single-process Flask entrypoint and request routing

- **Browser**: client · End-user and admin web client
- [Flask App](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/app.py): web entrypoint · Main Flask server and route dispatcher · `app.py`

### Domain Logic

Forecasting, analysis, intelligence, and shared helpers

- [Predictor](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/predictor.py): forecasting engine · Model selection, forecasting, backtesting, confidence intervals · `predictor.py`
- [Analyzer](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/analyzer.py): analysis engine · Consumer intelligence and general analytical processing · `analyzer.py`
- [Intelligence](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/intelligence.py): competitor engine · Competitor scoring, SWOT-style insights, market metrics · `intelligence.py`
- [Utils](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/utils.py): shared helpers · Common helper functions used across the app · `utils.py`

### Data & Persistence

SQLite state, ORM models, and uploaded datasets

- [ORM Models](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/database/models.py): sqlalchemy models · Database schema and persistence models · `database/models.py`
- [Market DB](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/instance/marketmind.db): sqlite store · Local embedded application database · `instance/marketmind.db`
- [Uploads](https://github.com/issu321/marketmind-intelegence-ai-system-based/tree/main/uploads): file store · Persisted user-uploaded CSV datasets · `uploads`
- [Example Data](https://github.com/issu321/marketmind-intelegence-ai-system-based/tree/main/Example-Datasets): seed files · Bundled dataset guide and sample CSVs · `Example-Datasets`

### Presentation

Server-rendered templates organized by workflow

- [Base Layout](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/base.html): shared template · Common server-rendered layout and navigation · `templates/base.html`
- [Dashboard](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/dashboard.html): home view · Main landing and executive overview pages · `templates/dashboard.html`
- [Forecasting UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/forecasting/index.html): workflow pages · Forecasting views for model runs and results · `templates/forecasting/index.html`
- [Insight Pages](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/competitors/index.html): workflow pages · Competitor, consumer, and opportunity views · `templates/competitors/index.html`
- [Reports UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/reports/index.html): report pages · Report generation, templates, and result views · `templates/reports/index.html`
- [Visuals UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/visualizations/index.html): chart pages · Plotly-backed visualization pages · `templates/visualizations/index.html`
- [Search UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/search/index.html): lookup pages · Cross-domain search and navigation surface · `templates/search/index.html`

### Operations

Authentication and admin surfaces

- [Admin UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/admin/dashboard.html): admin pages · Administrative dashboards for users, datasets, activity, and database · `templates/admin/dashboard.html`
- [Auth UI](https://github.com/issu321/marketmind-intelegence-ai-system-based/blob/main/templates/auth/login.html): account pages · Login, registration, and password recovery pages · `templates/auth/login.html`

## Connections

- Browser → Flask App: HTTP requests · Users interact with the Flask server
- Flask App → Predictor: forecasting · Routes delegate predictive workloads
- Flask App → Analyzer: analysis · Routes delegate consumer and dataset analysis
- Flask App → Intelligence: competitor intel · Routes delegate competitor intelligence workflows
- Flask App → Utils: helpers · Shared utility functions support route logic
- Flask App → ORM Models: persistence layer · Application state is mapped through ORM models
- ORM Models → Market DB: reads/writes · ORM persists data in the embedded SQLite database
- Flask App → Uploads: dataset upload · Uploaded CSV files are stored on disk
- Flask App → Example Data: seed data · Bundled example datasets support onboarding and demos
- Flask App → Base Layout: renders · Server-side pages extend the shared layout
- Flask App → Dashboard: renders · Main dashboard and landing pages are served from Flask
- Flask App → Forecasting UI: renders · Forecasting workflow pages present model outputs
- Flask App → Insight Pages: renders · Insight pages present competitor, consumer, and opportunity results
- Flask App → Reports UI: renders · Report pages present exported or composed results
- Flask App → Visuals UI: renders · Visualization pages embed chart outputs
- Flask App → Search UI: renders · Search pages expose cross-domain lookup
- Flask App → Admin UI: renders · Admin routes serve operational views
- Flask App → Auth UI: renders · Authentication routes serve account pages
- Forecasting UI → Predictor: drives · Forecasting pages trigger predictive pipelines
- Insight Pages → Analyzer: drives · Consumer and dataset analysis pages use analytics logic
- Insight Pages → Intelligence: drives · Competitor and opportunity pages use intelligence logic
- Reports UI → ORM Models: summarizes · Reports are composed from persisted entities and outputs
- Visuals UI → Analyzer: charts · Visualizations are built from analytical outputs
- Admin UI → ORM Models: administers · Admin screens inspect users, activity, datasets, and database state
- Search UI → ORM Models: queries · Search spans stored datasets, reports, and entities