# hackghosst001/cdr-ipdr-report-analyzer architecture

> Architecture diagram of the GitHub repository hackghosst001/cdr-ipdr-report-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hackghosst001/cdr-ipdr-report-analyzer
- Repository: https://github.com/hackghosst001/cdr-ipdr-report-analyzer

## Overview

1. **Overall shape**
   - This is a **client-side React + Vite single-page application** for analyzing **CDR/IPDR Excel or CSV reports**.
   - There is no backend in the repository; all upload handling, filtering, table rendering, and export logic appears to run **entirely in the browser**.

2. **Primary user flow**
   - The intended flow is:
     1. Enter case metadata and target number.
     2. Upload a report file.
     3. Inspect the loaded sheet data.
     4. Choose a query/analysis type.
     5. Review results.
     6. Export the filtered output to Excel.
   - This flow is described in the README and maps directly to the app’s page structure.

3. **App shell and routing**
   - `src/main.jsx` and `src/App.jsx` form the application entry and top-level composition.
   - The presence of `react-router-dom` and page components under `src/pages` indicates route-based navigation across:
     - `QueryInput`
     - `Sheet`
     - `QueryResult`
     - `About`
     - `Contact`
     - `UserGuide`
   - `Header` and `Footer` are shared layout components used across pages.

4. **Global application state**
   - `src/DataContext.jsx` is the main shared state boundary.
   - It likely stores the uploaded dataset, case metadata, selected target number, and computed query results so that different pages can access the same analysis state without prop drilling.
   - This context is the key bridge between file ingestion, sheet inspection, and query result rendering.

5. **Data ingestion and representation**
   - The app supports **Excel and CSV upload**, with SheetJS (`xlsx`) called out in the README.
   - Uploaded report data is likely normalized into row objects and held in memory for client-side processing.
   - `src/utils/rowKey.js` suggests rows may be assigned stable identifiers to support rendering, deduplication, or row tracking.

6. **Sheet inspection subsystem**
   - `src/Sheet.jsx` and `src/Sheet.css` indicate a dedicated sheet-view screen for browsing raw uploaded rows.
   - `src/components/ReusableTable.jsx` is the shared table renderer used for both sheet previews and query outputs.
   - The README notes that query result tables hide “A Party” fields, so the reusable table likely accepts column visibility rules or a sanitized result shape.

7. **Analysis engine: CDR filtering modules**
   - The `src/cdrFilter` directory is the core domain logic for investigations.
   - Each file represents a focused analysis rule or query type:
     - `durationFilter.js`
     - `maxCallDuration.js`
     - `frequentContact.js`
     - `timePattern.js`
     - `imeiTracking.js`
     - `imsiAnalysis.js`
     - `locationBTS.js`
   - `utils.js` in the same folder likely contains shared parsing, normalization, and comparison helpers used by multiple filters.
   - Architecturally, these modules are the “business logic” layer: they transform raw report rows into investigation outputs.

8. **Query result generation**
   - `src/pages/QueryInput.jsx` probably selects the analysis type and invokes the corresponding filter module.
   - `src/pages/QueryResult.jsx` displays the computed output in a table and exposes export actions.
   - `src/utils/reportUtils.js` likely handles formatting and export preparation, especially converting results into Excel-friendly structures.

9. **Formatting and presentation rules**
   - The README specifies two important presentation constraints:
     - Date-time values are shown as `DD-MM-YYYY HH:MM:SS`
     - Duration values are shown as `mm:ss`
   - That implies there is a formatting layer between raw parsed data and display/export output, most likely in `reportUtils.js` and/or the filter utilities.
   - The app is using Bootstrap 5 plus custom CSS files such as `App.css`, `Sheet.css`, and `index.css` for layout and styling.

10. **Navigation and informational pages**
   - `About`, `Contact`, and `UserGuide` are separate informational pages, indicating the app is packaged as a guided operator tool rather than a thin utility screen.
   - This is relevant for architecture because the analysis functionality is embedded in a broader workflow with documentation and operator guidance.

11. **Important boundaries**
   - The main architectural boundary is between:
     - **UI concerns**: pages, tables, navigation, styling
     - **Domain logic**: CDR/IPDR query filters and report transformations
     - **Shared state**: context-driven app data and selected analysis state
   - Keeping filter logic in `src/cdrFilter` separates investigative rules from rendering, which is important for maintainability and for adding new query types.

12. **External dependencies that matter**
   - **React**: component-based UI
   - **Vite**: build/dev toolchain
   - **React Router DOM**: page navigation
   - **Bootstrap 5**: layout and styling primitives
   - **SheetJS (`xlsx`)**: file parsing and Excel export
   - These are not incidental; they define the app as a browser-based data analysis tool with local file processing rather than a server-backed reporting system.

13. **What to show in an architecture diagram**
   - A clear diagram should center on:
     - Browser UI shell
     - File upload/input page
     - Shared context/store
     - CDR/IPDR filter engine
     - Sheet/result tables
     - Excel export path
   - The main data flow is: **uploaded file → parsed rows → context state → query filter module → formatted result set → table display/export**.

14. **Operational characteristics**
   - Because processing happens in the browser, the app likely favors privacy and offline-style usage for sensitive police/case data.
   - It also means memory and file-size constraints are architectural considerations, especially when loading large CDR/IPDR sheets.

Main entry points: [`src/App.jsx`](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/App.jsx) (App Shell), [`src/pages/QueryInput.jsx`](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryInput.jsx) (Query Input), [`src/cdrFilter/utils.js`](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/utils.js) (CDR Utils), [`src/pages/QueryResult.jsx`](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryResult.jsx) (Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["UI Shell"]
  node_node_main["Main<br/>entry<br/>[main.jsx]"]
  node_node_app["App Shell<br/>router-shell<br/>[App.jsx]"]
  node_node_header["Header<br/>layout<br/>[Header.jsx]"]
  node_node_footer["Footer<br/>layout<br/>[Footer.jsx]"]
  node_node_query_input["Query Input<br/>page<br/>[QueryInput.jsx]"]
  node_node_sheet["Sheet View<br/>page<br/>[Sheet.jsx]"]
  node_node_query_result["Results<br/>page<br/>[QueryResult.jsx]"]
  node_node_about["About<br/>page<br/>[About.jsx]"]
  node_node_contact_page["Contact<br/>page<br/>[Contact.jsx]"]
  node_node_userguide["Guide<br/>page<br/>[UserGuide.jsx]"]
end

subgraph group_group_state["Shared State"]
  node_node_context[("Data Context<br/>shared-state<br/>[DataContext.jsx]")]
end

subgraph group_group_analysis["Analysis Engine"]
  node_node_cdr_utils["CDR Utils<br/>filter-helpers<br/>[utils.js]"]
  node_node_duration["Duration Filter<br/>query-rule<br/>[durationFilter.js]"]
  node_node_maxcall["Max Call<br/>query-rule<br/>[maxCallDuration.js]"]
  node_node_freq_contact["Frequent Contact<br/>query-rule<br/>[frequentContact.js]"]
  node_node_timepattern["Time Pattern<br/>query-rule<br/>[timePattern.js]"]
  node_node_imei["IMEI Tracking<br/>query-rule<br/>[imeiTracking.js]"]
  node_node_imsi["IMSI Analysis<br/>query-rule<br/>[imsiAnalysis.js]"]
  node_node_bts["Location BTS<br/>query-rule<br/>[locationBTS.js]"]
end

subgraph group_group_output["Presentation & Export"]
  node_node_table["Reusable Table<br/>table-view<br/>[ReusableTable.jsx]"]
  node_node_report_utils["Report Utils<br/>format-export<br/>[reportUtils.js]"]
  node_node_row_key["Row Key<br/>row-id<br/>[rowKey.js]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"renders"| node_node_header
node_node_app -->|"renders"| node_node_footer
node_node_app -->|"route"| node_node_query_input
node_node_app -->|"route"| node_node_sheet
node_node_app -->|"route"| node_node_query_result
node_node_app -->|"route"| node_node_about
node_node_app -->|"route"| node_node_contact_page
node_node_app -->|"route"| node_node_userguide
node_node_query_input -->|"reads/writes"| node_node_context
node_node_sheet -->|"reads"| node_node_context
node_node_query_result -->|"reads"| node_node_context
node_node_query_input -->|"invokes"| node_node_duration
node_node_query_input -->|"invokes"| node_node_maxcall
node_node_query_input -->|"invokes"| node_node_freq_contact
node_node_query_input -->|"invokes"| node_node_timepattern
node_node_query_input -->|"invokes"| node_node_imei
node_node_query_input -->|"invokes"| node_node_imsi
node_node_query_input -->|"invokes"| node_node_bts
node_node_duration -->|"uses"| node_node_cdr_utils
node_node_maxcall -->|"uses"| node_node_cdr_utils
node_node_freq_contact -->|"uses"| node_node_cdr_utils
node_node_timepattern -->|"uses"| node_node_cdr_utils
node_node_imei -->|"uses"| node_node_cdr_utils
node_node_imsi -->|"uses"| node_node_cdr_utils
node_node_bts -->|"uses"| node_node_cdr_utils
node_node_sheet -->|"renders"| node_node_table
node_node_query_result -->|"renders"| node_node_table
node_node_query_result -->|"formats/export"| node_node_report_utils
node_node_report_utils -->|"uses"| node_node_row_key

click node_node_main "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/main.jsx"
click node_node_app "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/App.jsx"
click node_node_header "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/Header.jsx"
click node_node_footer "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/Footer.jsx"
click node_node_query_input "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryInput.jsx"
click node_node_sheet "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/Sheet.jsx"
click node_node_query_result "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryResult.jsx"
click node_node_about "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/About.jsx"
click node_node_contact_page "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/Contact.jsx"
click node_node_userguide "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/UserGuide.jsx"
click node_node_context "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/DataContext.jsx"
click node_node_table "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/ReusableTable.jsx"
click node_node_report_utils "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/utils/reportUtils.js"
click node_node_row_key "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/utils/rowKey.js"
click node_node_cdr_utils "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/utils.js"
click node_node_duration "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/durationFilter.js"
click node_node_maxcall "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/maxCallDuration.js"
click node_node_freq_contact "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/frequentContact.js"
click node_node_timepattern "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/timePattern.js"
click node_node_imei "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/imeiTracking.js"
click node_node_imsi "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/imsiAnalysis.js"
click node_node_bts "https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/locationBTS.js"

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_node_main,node_node_app,node_node_header,node_node_footer,node_node_query_input,node_node_sheet,node_node_query_result,node_node_about,node_node_contact_page,node_node_userguide toneBlue
class node_node_context toneAmber
class node_node_cdr_utils,node_node_duration,node_node_maxcall,node_node_freq_contact,node_node_timepattern,node_node_imei,node_node_imsi,node_node_bts toneMint
class node_node_table,node_node_report_utils,node_node_row_key toneRose
```

## Components

### UI Shell

App composition, routing, shared layout, and page screens.

- [Main](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/main.jsx): entry · Vite/React entry that boots the app. · `src/main.jsx`
- [App Shell](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/App.jsx): router-shell · Top-level composition and route wiring. · `src/App.jsx`
- [Header](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/Header.jsx): layout · Shared top navigation and page chrome. · `src/components/Header.jsx`
- [Footer](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/Footer.jsx): layout · Shared bottom page chrome. · `src/components/Footer.jsx`
- [Query Input](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryInput.jsx): page · Case metadata entry and analysis selection screen. · `src/pages/QueryInput.jsx`
- [Sheet View](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/Sheet.jsx): page · Raw uploaded sheet inspection screen. · `src/Sheet.jsx`
- [Results](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/QueryResult.jsx): page · Computed query output and export screen. · `src/pages/QueryResult.jsx`
- [About](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/About.jsx): page · Informational page about the tool. · `src/pages/About.jsx`
- [Contact](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/Contact.jsx): page · Support or contact information page. · `src/pages/Contact.jsx`
- [Guide](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/pages/UserGuide.jsx): page · Operator guidance and usage instructions. · `src/pages/UserGuide.jsx`

### Shared State

Browser-side shared data and cross-page analysis state.

- [Data Context](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/DataContext.jsx): shared-state · Cross-page browser state for uploaded data and analysis selections. · `src/DataContext.jsx`

### Analysis Engine

CDR/IPDR query and filtering logic.

- [CDR Utils](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/utils.js): filter-helpers · Shared parsing and comparison helpers for investigative filters. · `src/cdrFilter/utils.js`
- [Duration Filter](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/durationFilter.js): query-rule · Duration-based filtering and aggregation logic. · `src/cdrFilter/durationFilter.js`
- [Max Call](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/maxCallDuration.js): query-rule · Finds the longest or peak-duration call record. · `src/cdrFilter/maxCallDuration.js`
- [Frequent Contact](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/frequentContact.js): query-rule · Identifies repeated contacts and communication patterns. · `src/cdrFilter/frequentContact.js`
- [Time Pattern](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/timePattern.js): query-rule · Clusters calls by time-of-day or temporal pattern. · `src/cdrFilter/timePattern.js`
- [IMEI Tracking](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/imeiTracking.js): query-rule · Tracks device identifiers across report rows. · `src/cdrFilter/imeiTracking.js`
- [IMSI Analysis](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/imsiAnalysis.js): query-rule · Analyzes subscriber identifier usage and movement. · `src/cdrFilter/imsiAnalysis.js`
- [Location BTS](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/cdrFilter/locationBTS.js): query-rule · Infers location behavior from BTS or tower data. · `src/cdrFilter/locationBTS.js`

### Presentation & Export

Table rendering and export/formatting helpers.

- [Reusable Table](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/components/ReusableTable.jsx): table-view · Shared table renderer for sheet preview and query results. · `src/components/ReusableTable.jsx`
- [Report Utils](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/utils/reportUtils.js): format-export · Result shaping, formatting, and Excel export preparation. · `src/utils/reportUtils.js`
- [Row Key](https://github.com/hackghosst001/cdr-ipdr-report-analyzer/blob/main/src/utils/rowKey.js): row-id · Stable row identification helper for tracked records. · `src/utils/rowKey.js`

## Connections

- Main → App Shell: boots · Application entry mounts the top-level app.
- App Shell → Header: renders · Shared header is included in the app shell.
- App Shell → Footer: renders · Shared footer is included in the app shell.
- App Shell → Query Input: route · Navigation opens the input and analysis setup page.
- App Shell → Sheet View: route · Navigation opens the raw sheet inspection page.
- App Shell → Results: route · Navigation opens the query result page.
- App Shell → About: route · Navigation opens the about page.
- App Shell → Contact: route · Navigation opens the contact page.
- App Shell → Guide: route · Navigation opens the user guide page.
- Query Input → Data Context: reads/writes · Case metadata, target number, and file state flow through shared context.
- Sheet View → Data Context: reads · Sheet view consumes uploaded rows from shared context.
- Results → Data Context: reads · Result view consumes computed analysis state from shared context.
- Query Input → Duration Filter: invokes · Query selection can dispatch to duration analysis.
- Query Input → Max Call: invokes · Query selection can dispatch to max call analysis.
- Query Input → Frequent Contact: invokes · Query selection can dispatch to frequent contact analysis.
- Query Input → Time Pattern: invokes · Query selection can dispatch to time-pattern analysis.
- Query Input → IMEI Tracking: invokes · Query selection can dispatch to IMEI tracking.
- Query Input → IMSI Analysis: invokes · Query selection can dispatch to IMSI analysis.
- Query Input → Location BTS: invokes · Query selection can dispatch to BTS location analysis.
- Duration Filter → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- Max Call → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- Frequent Contact → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- Time Pattern → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- IMEI Tracking → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- IMSI Analysis → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- Location BTS → CDR Utils: uses · Filter logic relies on shared normalization helpers.
- Sheet View → Reusable Table: renders · Sheet preview is shown through the shared table component.
- Results → Reusable Table: renders · Computed results are shown through the shared table component.
- Results → Report Utils: formats/export · Results are prepared and exported through report utilities.
- Report Utils → Row Key: uses · Export and formatting logic can preserve stable row identity.
