# marwaneproo/perdicia architecture

> Architecture diagram of the GitHub repository marwaneproo/perdicia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marwaneproo/perdicia
- Repository: https://github.com/marwaneproo/perdicia

## Overview

PERDICIA is a local-workspace business intelligence platform: users upload or choose a dataset, then inspect its quality and preview, explore filtered KPIs and charts, view rule-based insights or a statistical forecast, and export results. The frontend’s page-to-API relationships and backend route dispatch are supported by the source index and routes excerpt; backend helper implementations are partly unsampled, so their internal relationships are limited to those explicitly shown or indexed.

Main entry points: [`backend/app/routes.py`](https://github.com/marwaneproo/perdicia/blob/main/backend/app/routes.py) (API routes), [`frontend/src/App.tsx`](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/services/api.ts`](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/services/api.ts) (API client), [`frontend/src/pages/DataManagement.tsx`](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/DataManagement.tsx) (Data management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["App routing<br/>[App.tsx]"]
  node_layout["Workspace layout<br/>[AppLayout.tsx]"]
  node_preview["Dataset preview<br/>[DataManagement.tsx]"]
end

subgraph group_ingestion["Dataset Ingestion"]
  node_management["Data management<br/>[DataManagement.tsx]"]
  node_dataset_state["Dataset state<br/>[useDataset.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_routes["API routes<br/>[routes.py]"]
  node_dataset_db[("Dataset registry<br/>[database.py]")]
  node_file_storage[("Uploaded files")]
end

subgraph group_analysis["Analytics"]
  node_analysis_core["Profiling &amp; KPIs<br/>[analysis.py]"]
  node_overview["Business overview<br/>[Overview.tsx]"]
  node_analytics_ui["Analytics studio<br/>[Analytics.tsx]"]
  node_visualizations["Chart suggestions<br/>[visualization.py]"]
  node_insights_ui["Business insights<br/>[Insights.tsx]"]
  node_insights_engine["Insight rules<br/>[insights.py]"]
  node_forecast_ui["Forecast view<br/>[Forecast.tsx]"]
  node_forecast_engine["Forecast baseline<br/>[forecasting.py]"]
end

subgraph group_delivery["Results &amp; Plans"]
  node_export_engine["Report exports<br/>[export.py]"]
  node_pricing["Pricing plans<br/>[Pricing.tsx]"]
  node_subscription["Plan state"]
end

node_user(("Business user"))
node_external(("Browser / API consumer"))

node_user -->|"uses workspace"| node_app
node_app -->|"routes to"| node_management
node_app -->|"routes to"| node_overview
node_app -->|"routes to"| node_analytics_ui
node_app -->|"routes to"| node_insights_ui
node_app -->|"routes to"| node_forecast_ui
node_app -->|"routes to"| node_pricing
node_app -->|"renders pages in"| node_layout
node_management -->|"uploads or selects"| node_dataset_state
node_dataset_state -->|"requests datasets"| node_api_client
node_api_client -.->|"calls API"| node_routes
node_routes -->|"loads and profiles"| node_analysis_core
node_routes -->|"registers and looks up"| node_dataset_db
node_routes -->|"writes uploaded files"| node_file_storage
node_routes -->|"builds charts"| node_visualizations
node_routes -->|"builds insights"| node_insights_engine
node_routes -->|"computes forecast"| node_forecast_engine
node_routes -->|"creates exports"| node_export_engine
node_management -->|"shows preview"| node_preview
node_overview -->|"requests overview data"| node_api_client
node_analytics_ui -->|"requests analysis"| node_api_client
node_insights_ui -->|"requests insights"| node_api_client
node_forecast_ui -->|"requests forecast"| node_api_client
node_pricing -->|"chooses plan"| node_subscription
node_external -.->|"receives downloads"| node_routes

click node_app "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/App.tsx"
click node_layout "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/layouts/AppLayout.tsx"
click node_management "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/DataManagement.tsx"
click node_dataset_state "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/hooks/useDataset.tsx"
click node_api_client "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/services/api.ts"
click node_routes "https://github.com/marwaneproo/perdicia/blob/main/backend/app/routes.py"
click node_analysis_core "https://github.com/marwaneproo/perdicia/blob/main/backend/app/analysis.py"
click node_dataset_db "https://github.com/marwaneproo/perdicia/blob/main/backend/app/database.py"
click node_file_storage "https://github.com/marwaneproo/perdicia/tree/main/backend/storage"
click node_preview "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/DataManagement.tsx"
click node_overview "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Overview.tsx"
click node_analytics_ui "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Analytics.tsx"
click node_visualizations "https://github.com/marwaneproo/perdicia/blob/main/backend/app/visualization.py"
click node_insights_ui "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Insights.tsx"
click node_insights_engine "https://github.com/marwaneproo/perdicia/blob/main/backend/app/insights.py"
click node_forecast_ui "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Forecast.tsx"
click node_forecast_engine "https://github.com/marwaneproo/perdicia/blob/main/backend/app/forecasting.py"
click node_export_engine "https://github.com/marwaneproo/perdicia/blob/main/backend/app/export.py"
click node_pricing "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Pricing.tsx"
click node_subscription "https://github.com/marwaneproo/perdicia/blob/main/frontend/src/hooks/useSubscription.tsx"

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_app,node_layout,node_preview,node_user,node_external toneBlue
class node_management,node_dataset_state,node_api_client,node_routes,node_dataset_db,node_file_storage toneAmber
class node_analysis_core,node_overview,node_analytics_ui,node_visualizations,node_insights_ui,node_insights_engine,node_forecast_ui,node_forecast_engine toneMint
class node_export_engine,node_pricing,node_subscription toneRose
```

## Components

### Workspace UI

- [App routing](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Workspace layout](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/layouts/AppLayout.tsx): `frontend/src/layouts/AppLayout.tsx`
- [Dataset preview](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/DataManagement.tsx): `frontend/src/pages/DataManagement.tsx`

### Dataset Ingestion

- [Data management](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/DataManagement.tsx): `frontend/src/pages/DataManagement.tsx`
- [Dataset state](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/hooks/useDataset.tsx): `frontend/src/hooks/useDataset.tsx`
- [API client](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [API routes](https://github.com/marwaneproo/perdicia/blob/main/backend/app/routes.py): `backend/app/routes.py`
- [Dataset registry](https://github.com/marwaneproo/perdicia/blob/main/backend/app/database.py): `backend/app/database.py`
- [Uploaded files](https://github.com/marwaneproo/perdicia/tree/main/backend/storage): `backend/storage`

### Analytics

- [Profiling & KPIs](https://github.com/marwaneproo/perdicia/blob/main/backend/app/analysis.py): `backend/app/analysis.py`
- [Business overview](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Overview.tsx): `frontend/src/pages/Overview.tsx`
- [Analytics studio](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Analytics.tsx): `frontend/src/pages/Analytics.tsx`
- [Chart suggestions](https://github.com/marwaneproo/perdicia/blob/main/backend/app/visualization.py): `backend/app/visualization.py`
- [Business insights](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Insights.tsx): `frontend/src/pages/Insights.tsx`
- [Insight rules](https://github.com/marwaneproo/perdicia/blob/main/backend/app/insights.py): `backend/app/insights.py`
- [Forecast view](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Forecast.tsx): `frontend/src/pages/Forecast.tsx`
- [Forecast baseline](https://github.com/marwaneproo/perdicia/blob/main/backend/app/forecasting.py): `backend/app/forecasting.py`

### Results & Plans

- [Report exports](https://github.com/marwaneproo/perdicia/blob/main/backend/app/export.py): `backend/app/export.py`
- [Pricing plans](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/pages/Pricing.tsx): `frontend/src/pages/Pricing.tsx`
- [Plan state](https://github.com/marwaneproo/perdicia/blob/main/frontend/src/hooks/useSubscription.tsx): `frontend/src/hooks/useSubscription.tsx`

### Other components

- **Business user**
- **Browser / API consumer**

## Connections

- Business user → App routing: uses workspace (evidence: `frontend/src/App.tsx`)
- App routing → Data management: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Business overview: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Analytics studio: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Business insights: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Forecast view: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Pricing plans: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Workspace layout: renders pages in (evidence: `frontend/src/App.tsx`)
- Data management → Dataset state: uploads or selects (evidence: `frontend/src/pages/DataManagement.tsx`)
- Dataset state → API client: requests datasets (evidence: `frontend/src/hooks/useDataset.tsx`)
- API client → API routes: calls API
- API routes → Profiling & KPIs: loads and profiles (evidence: `backend/app/routes.py`)
- API routes → Dataset registry: registers and looks up (evidence: `backend/app/routes.py`)
- API routes → Uploaded files: writes uploaded files (evidence: `backend/app/routes.py`)
- API routes → Chart suggestions: builds charts (evidence: `backend/app/routes.py`)
- API routes → Insight rules: builds insights (evidence: `backend/app/routes.py`)
- API routes → Forecast baseline: computes forecast (evidence: `backend/app/routes.py`)
- API routes → Report exports: creates exports (evidence: `backend/app/routes.py`)
- Data management → Dataset preview: shows preview (evidence: `frontend/src/pages/DataManagement.tsx`)
- Business overview → API client: requests overview data (evidence: `frontend/src/pages/Overview.tsx`)
- Analytics studio → API client: requests analysis (evidence: `frontend/src/pages/Analytics.tsx`)
- Business insights → API client: requests insights (evidence: `frontend/src/pages/Insights.tsx`)
- Forecast view → API client: requests forecast (evidence: `frontend/src/pages/Forecast.tsx`)
- Pricing plans → Plan state: chooses plan (evidence: `frontend/src/pages/Pricing.tsx`)
- Browser / API consumer → API routes: receives downloads
