DataPulse is a business dashboard that turns raw sales and transaction data into clear charts, forecasts, and reports. It is designed to be used as a product, not as a technical project, so a business owner or examiner can understand it without reading code.
DataPulse uses role-based access control so different people see different parts of the system.
- Admins can manage users, update business goals, run forecasts, and use the data pipeline.
- Viewers can see the dashboard and reports, but cannot access sensitive admin-only features.
Info: This keeps important actions like deleting data or changing users limited to the right people.
The Analytics Hub is the control center of the app. It is the starting point for moving between the main business areas.
This is the main dashboard. It takes raw numbers and turns them into useful visuals such as:
- Revenue charts
- Order counts
- Average order value
- Trend charts over time
- Forecast charts
The dashboard also responds to the Date Range filter, so you can focus on a week, a month, or a custom period.
The AI Forecast uses a forecasting engine called Prophet. It looks at past sales history and predicts future sales.
This helps with:
- Inventory planning
- Revenue planning
- Staffing decisions
- Business forecasting
Info: The forecast is based on historical patterns, so it becomes more useful as more data is added.
This section is for the owner or Admin. It is where you:
- Manage team access
- Add or remove users
- Set target goals
- Review system logs
- Clean or reset data when needed
DataPulse is business-agnostic. That means it can work with many different kinds of sales or transaction datasets, not just one specific company.
- CSV files only
To work correctly, the data should include these fields:
- A date column: tells the app when the transaction happened
- A value column: tells the app the amount, price, or revenue
- A unique ID column: identifies each record, such as an order number
- A customer or user column: identifies who made the purchase
Warning: If the column names in your CSV are different, you must map them correctly before the dashboard will read them properly.
You do not need to change Python logic to use a different dataset. Instead, update the column mapping settings.
Open:
Update the values for:
DATE_COLVALUE_COLID_COLUSER_COL
Example:
date_col = "order_purchase_timestamp"
value_col = "price"
id_col = "order_id"
user_col = "customer_unique_id"If your version of the project uses a YAML-based mapping file, update the same column names there instead.
The goal is the same: match the names in the system to the names in your CSV file.
Info: You only change the mapping values. You do not need to rewrite the application logic.
Make sure your CSV file contains the required columns:
- a date field
- a value field
- a unique record ID
If possible, keep the file clean and simple:
- one header row
- one record per row
- no merged cells
- CSV format only
Open src/config/column_mapping.py and change the mapping values so they match the headers in your CSV file.
For example, if your file uses sale_date instead of order_purchase_timestamp, update the date mapping to sale_date.
If your dataset uses different names, change only the mapping values, not the rest of the application.
Log in as an Admin and go to Data Pipeline.
From there you can:
- Upload or sync the data
- Load the raw files into the system
- Refresh the dashboard data
- Run the forecast
Go to Business Insights to see:
- Charts
- KPI cards
- Forecasts
- Exportable reports
This is a simple guide to the folders and files in the project.
- app.py - the main Streamlit app that opens the product and routes between pages
- README.md - this guide
- requirements.txt - the Python packages needed to run the app
- .env - private environment settings such as the database connection
- data/raw/ - place incoming CSV files here before loading them into the system
- data/processed/ - stores prepared or cleaned data if needed
- src/config/ - dataset mapping and business configuration
- src/services/ - business logic such as login, forecasts, KPI calculations, and data loading
- src/components/ - pipeline tools such as ingestion and transformation
- src/pages/ - the Streamlit pages for login, hub, insights, pipeline, and settings
- src/ui/ - shared styling and reusable interface helpers
- src/utils.py - database helpers and utility functions
- tests/ - automated checks that confirm the system still works
- notebooks/ - optional analysis notebooks
- deliverables/ - project materials and submission assets
Info: You do not need to open every file to use the product. Most users only need the app, the data folder, and the column mapping settings.
You can download filtered dashboard data as a CSV file.
This is useful for:
- meetings
- reporting
- sharing results with stakeholders
The target goal feature lets you compare actual performance against a business target.
This helps you quickly see whether sales are tracking above or below your goal.
- Data is stored securely in the cloud using Supabase.
- The app is responsive and works on mobile browsers as well as desktop.
If you are using DataPulse as a business owner, your normal workflow is:
- Log in
- Open the Analytics Hub
- Review Business Insights
- Adjust the Date Range if needed
- Download a report for meetings
- Check the forecast before making planning decisions
Info: Viewers can safely use the dashboard, while Admins handle team management and operational settings.
This section is for developers or technical examiners.
DataPulse/
├── app.py
├── README.md
├── requirements.txt
├── .env
├── data/
│ ├── raw/
│ └── processed/
├── deliverables/
├── notebooks/
├── src/
│ ├── config/
│ │ ├── __init__.py
│ │ └── column_mapping.py
│ ├── components/
│ │ ├── __init__.py
│ │ ├── data_ingestion.py
│ │ ├── data_transformation.py
│ │ └── prediction_pipeline.py
│ ├── pages/
│ │ ├── __init__.py
│ │ ├── login.py
│ │ ├── home.py
│ │ ├── insights.py
│ │ ├── pipeline.py
│ │ └── settings.py
│ ├── services/
│ │ ├── __init__.py
│ │ ├── auth_service.py
│ │ ├── data_service.py
│ │ ├── forecast_service.py
│ │ └── kpi_service.py
│ ├── ui/
│ │ ├── __init__.py
│ │ ├── components.py
│ │ ├── helpers.py
│ │ └── styles.py
│ └── utils.py
└── tests/
├── test_kpis.py
└── test_streamlit_supabase_integration.py
- app.py is the main entry point. It loads the app, checks whether the user is logged in, routes to the correct page, and connects all page modules together.
- README.md explains how to use the product and how the project is organized.
- requirements.txt lists the Python libraries required to run the app.
- .env stores private environment values such as the Supabase database URL and column mapping settings.
- data/raw/ is where you place the original CSV files before uploading them into the system.
- data/processed/ is for cleaned or prepared data outputs when needed.
- src/config/ contains the business mapping and dataset configuration.
- src/config/column_mapping.py defines which CSV columns represent dates, values, IDs, and optional customer fields.
- src/config/init.py exposes the configuration objects for easy import elsewhere in the app.
- src/components/data_ingestion.py reads CSV files from
data/raw/, cleans column names, and uploads them to Supabase. - src/components/data_transformation.py combines raw tables into a business-ready analytics table.
- src/components/prediction_pipeline.py runs the forecasting pipeline as a standalone process.
- src/components/init.py marks the directory as a Python package.
- src/pages/login.py renders the login form and authenticates users.
- src/pages/home.py renders the Analytics Hub / control center.
- src/pages/insights.py renders the Business Insights dashboard, charts, and data table.
- src/pages/pipeline.py renders the data pipeline and forecast controls for Admins.
- src/pages/settings.py renders user management, goals, logs, and reset tools.
- src/pages/init.py marks the directory as a Python package.
- src/services/auth_service.py handles authentication, password hashing, and user management.
- src/services/data_service.py loads dashboard data from the database.
- src/services/forecast_service.py prepares data, trains Prophet, and saves forecast results.
- src/services/kpi_service.py calculates metrics such as revenue, order count, and average order value.
- src/services/init.py marks the directory as a Python package.
- src/ui/styles.py contains the shared page styling and layout setup.
- src/ui/components.py contains shared navigation and sidebar rendering.
- src/ui/helpers.py contains reusable chart and formatting helpers.
- src/ui/init.py marks the directory as a Python package.
- src/utils.py contains shared database helpers, logging, and low-level data access functions.
- tests/test_kpis.py checks KPI calculations.
- tests/test_streamlit_supabase_integration.py checks that the app can load data from the database correctly.
Info: The app is intentionally split this way so each file has one clear job and can be maintained without touching the whole system.
cd DataPulse
python -m venv venv
source venv/Scripts/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtCreate a .env file in the project root and add your Supabase connection string:
DATABASE_URL="postgresql://user:password@host:port/database"streamlit run app.pyapp.py- main Streamlit router and page launchersrc/pages/- page modules for login, hub, insights, pipeline, and settingssrc/ui/- shared styling and UI helperssrc/services/- business logic for authentication, KPI calculations, and forecastingsrc/components/- ingestion, transformation, and pipeline execution utilitiessrc/config/- dataset mapping and environment-driven settingssrc/utils.py- database helpers, logging, and CRUD support
pytest -v