# yashsolanki466-hash/bestreport architecture

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

- Interactive diagram: https://gitdiagram.com/yashsolanki466-hash/bestreport
- Repository: https://github.com/yashsolanki466-hash/bestreport

## Overview

1. **What this repo is**
   - This is a filesystem-to-HTML report generator for NGS project folders.
   - The core architecture is a pipeline that reads a standardized project directory, extracts metrics and metadata, normalizes them into a report model, then renders one or more HTML reports.

2. **Primary inputs**
   - The main input boundary is a project root with a fixed lab-style layout, such as `01_Raw_Data`, `02_reference_genome_and_gff`, and other result folders.
   - Per-project metadata can be supplied through `metadata.json` in the project root; this overrides hardcoded defaults and reduces manual configuration.
   - Global/static configuration also comes from repo files such as `config.yaml`, `config/default_snippets.json`, and `report_static_content.json`.

3. **Discovery and validation layer**
   - `validate.ts`, `paths.ts`, `config.ts`, and `statsDiscovery.ts` form the intake gate.
   - Their job is to resolve expected folders/files, detect which data products are present, and fail or warn when the project tree is incomplete or nonstandard.
   - This layer is the main boundary between arbitrary filesystem contents and the rest of the pipeline.

4. **Parsing and data extraction**
   - `dataParser.ts`, `gtfParser.ts`, `fastaStats.ts`, and `columnUtils.ts` handle domain-specific extraction.
   - These modules convert raw report inputs like annotation files, FASTA-derived stats, and tabular outputs into normalized in-memory data.
   - `types.ts` and `reportModel.ts` define the shape of the structured data used downstream.

5. **Report assembly**
   - `reportGenerator.ts` is the main composition layer.
   - It takes the validated project metadata plus parsed statistics and assembles them into a complete report structure.
   - The output is not just a data object; it is prepared specifically for templating and final HTML generation.

6. **Templating and presentation**
   - The repo keeps multiple report templates under `templates/`, including `report_full.ejs`, `report_comprehensive.ejs`, `report_interim.ejs`, `report_original.ejs`, and others.
   - There is also a raw HTML template (`report_template.html`) and a specialized `templates/busi.html`, suggesting multiple presentation variants for different report formats or clients.
   - `embedAssets.ts` indicates that assets are inlined or packaged into the final HTML for portability.

7. **Automation entry points**
   - `cli.ts` is the single-project command-line entry point.
   - `batch.ts` adds multi-project generation by scanning a root directory.
   - `watch.ts` adds polling-based automation so a report can be generated once a project folder becomes “ready” based on filesystem conditions.
   - These are orchestration layers over the same core parsing/rendering pipeline.

8. **Browser/UI surface**
   - The repo also contains a browser-facing React/Vite application (`src/main.tsx`, `src/App.tsx`, `src/index.css`, plus root `App.tsx`/`components`).
   - This looks like a UI layer for previewing or interacting with report content, separate from the CLI pipeline.
   - `vite.config.ts`, `tailwind.config.cjs`, and `postcss.config.cjs` show that the frontend is built as a distinct bundle.

9. **Specialized interim app**
   - `interim_app/` is a separate, self-contained Vite app with its own `App.tsx`, `main.tsx`, `index.html`, template, and built output.
   - It appears to be a narrow or transitional report UI used for an interim report format, not the primary generation path.

10. **Build/runtime shape**
   - The checked-in `dist/` directory contains compiled JS, type declarations, tests, and browser assets, so the repo ships both Node-side and browser-side artifacts.
   - Architecturally, this is a TypeScript project with a compiled distribution layer; the same source tree supports CLI execution and static HTML output.

11. **Testing boundaries**
   - Unit tests exist for parsers and utilities (`dataParser.test.ts`, `gtfParser.test.ts`, `columnUtils.test.ts`) along with test setup/mocks under `src/test/`.
   - This suggests the parsing and normalization layers are intentionally isolated and testable without the full report-generation flow.

12. **Overall data flow**
   - Filesystem project folder -> validation/discovery -> domain parsers/stats extraction -> normalized report model -> template rendering -> final HTML report.
   - Batch and watcher modes reuse the same pipeline, differing only in how projects are discovered and when generation is triggered.

Main entry points: [`src/reportGenerator.ts`](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportGenerator.ts) (Report generator), [`src/statsDiscovery.ts`](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/statsDiscovery.ts) (Discover stats), [`src/validate.ts`](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/validate.ts) (Validate), [`src/reportModel.ts`](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportModel.ts) (Report model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs & config"]
  node_config_yaml["config.yaml<br/>project config<br/>[config.yaml]"]
  node_default_snippets["Default snippets<br/>static content"]
  node_static_content["Static content<br/>content manifest"]
end

subgraph group_core["Core pipeline"]
  node_paths["Paths<br/>resolver<br/>[paths.ts]"]
  node_validate["Validate<br/>gatekeeper<br/>[validate.ts]"]
  node_stats_discovery["Discover stats<br/>scanner<br/>[statsDiscovery.ts]"]
  node_config["Config load<br/>[config.ts]"]
  node_data_parser["Data parser<br/>tabular parser<br/>[dataParser.ts]"]
  node_gtf_parser["GTF parser<br/>annotation parser<br/>[gtfParser.ts]"]
  node_fasta_stats["FASTA stats<br/>sequence stats<br/>[fastaStats.ts]"]
  node_column_utils["Column utils<br/>normalizer<br/>[columnUtils.ts]"]
  node_report_model["Report model<br/>schema<br/>[reportModel.ts]"]
  node_report_generator["Report generator<br/>assembler<br/>[reportGenerator.ts]"]
end

subgraph group_present["Templates & output"]
  node_embed_assets["Embed assets<br/>packager<br/>[embedAssets.ts]"]
  node_templates["Templates<br/>html/ejs views<br/>[report_full.ejs]"]
  node_template_html["HTML shell<br/>html template"]
end

subgraph group_automation["Automation"]
  node_batch["Batch mode<br/>orchestrator<br/>[batch.ts]"]
  node_cli["CLI<br/>entrypoint<br/>[cli.ts]"]
  node_watch["Watch mode<br/>polling runner<br/>[watch.ts]"]
end

subgraph group_ui["Browser UI"]
  node_main_ui(("Main app<br/>react app<br/>[main.tsx]"))
  node_app_ui["App shell<br/>react shell<br/>[App.tsx]"]
  node_interim_app(("Interim app<br/>vite app<br/>[App.tsx]"))
end

node_config_yaml -->|"runtime config"| node_config
node_default_snippets -->|"snippets"| node_report_generator
node_static_content -->|"content"| node_report_generator
node_config -->|"settings"| node_paths
node_paths -->|"expected layout"| node_validate
node_validate -->|"ready tree"| node_stats_discovery
node_stats_discovery -->|"discovered inputs"| node_data_parser
node_stats_discovery -->|"annotation inputs"| node_gtf_parser
node_stats_discovery -->|"sequence inputs"| node_fasta_stats
node_data_parser -->|"tabular shape"| node_column_utils
node_gtf_parser -->|"annotation data"| node_report_model
node_fasta_stats -->|"assembly stats"| node_report_model
node_data_parser -->|"normalized metrics"| node_report_model
node_report_model -->|"schema"| node_report_generator
node_config -->|"metadata"| node_report_generator
node_report_generator -->|"render data"| node_templates
node_report_generator -->|"html data"| node_template_html
node_templates -->|"assets"| node_embed_assets
node_template_html -->|"assets"| node_embed_assets
node_cli -->|"single project"| node_report_generator
node_batch -->|"multi-project scan"| node_validate
node_watch -->|"ready check"| node_validate
node_main_ui -->|"ui shell"| node_app_ui
node_interim_app -->|"interim UI"| node_templates

click node_config_yaml "https://github.com/yashsolanki466-hash/bestreport/blob/main/config.yaml"
click node_default_snippets "https://github.com/yashsolanki466-hash/bestreport/blob/main/config/default_snippets.json"
click node_static_content "https://github.com/yashsolanki466-hash/bestreport/blob/main/report_static_content.json"
click node_paths "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/paths.ts"
click node_validate "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/validate.ts"
click node_stats_discovery "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/statsDiscovery.ts"
click node_config "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/config.ts"
click node_data_parser "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/dataParser.ts"
click node_gtf_parser "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/gtfParser.ts"
click node_fasta_stats "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/fastaStats.ts"
click node_column_utils "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/columnUtils.ts"
click node_report_model "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportModel.ts"
click node_report_generator "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportGenerator.ts"
click node_embed_assets "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/embedAssets.ts"
click node_templates "https://github.com/yashsolanki466-hash/bestreport/blob/main/templates/report_full.ejs"
click node_template_html "https://github.com/yashsolanki466-hash/bestreport/blob/main/templates/report_template.html"
click node_batch "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/batch.ts"
click node_cli "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/cli.ts"
click node_watch "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/watch.ts"
click node_main_ui "https://github.com/yashsolanki466-hash/bestreport/blob/main/src/main.tsx"
click node_app_ui "https://github.com/yashsolanki466-hash/bestreport/blob/main/App.tsx"
click node_interim_app "https://github.com/yashsolanki466-hash/bestreport/blob/main/interim_app/App.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_config_yaml,node_default_snippets,node_static_content toneBlue
class node_paths,node_validate,node_stats_discovery,node_config,node_data_parser,node_gtf_parser,node_fasta_stats,node_column_utils,node_report_model,node_report_generator toneAmber
class node_embed_assets,node_templates,node_template_html toneMint
class node_batch,node_cli,node_watch toneRose
class node_main_ui,node_app_ui,node_interim_app toneIndigo
```

## Components

### Inputs & config

Project folders, metadata, and static configuration that feed the generator.

- [config.yaml](https://github.com/yashsolanki466-hash/bestreport/blob/main/config.yaml): project config · Primary repository-level configuration for report generation. · `config.yaml`
- [Default snippets](https://github.com/yashsolanki466-hash/bestreport/blob/main/config/default_snippets.json): static content · Shared snippet defaults used when assembling report text and content. · `config/default_snippets.json`
- [Static content](https://github.com/yashsolanki466-hash/bestreport/blob/main/report_static_content.json): content manifest · Repository-provided static report content overrides and defaults. · `report_static_content.json`

### Core pipeline

Discovery, parsing, modeling, and report assembly.

- [Paths](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/paths.ts): resolver · Resolves expected project directories and file locations. · `src/paths.ts`
- [Validate](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/validate.ts): gatekeeper · Checks project layout, file presence, and readiness conditions. · `src/validate.ts`
- [Discover stats](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/statsDiscovery.ts): scanner · Detects available data products and report inputs in the project tree. · `src/statsDiscovery.ts`
- [Config load](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/config.ts): config loader · Loads and merges runtime configuration and project metadata. · `src/config.ts`
- [Data parser](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/dataParser.ts): tabular parser · Normalizes report tables and extracted metrics into structured data. · `src/dataParser.ts`
- [GTF parser](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/gtfParser.ts): annotation parser · Extracts annotation features from GTF inputs. · `src/gtfParser.ts`
- [FASTA stats](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/fastaStats.ts): sequence stats · Derives assembly and sequence metrics from FASTA-derived inputs. · `src/fastaStats.ts`
- [Column utils](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/columnUtils.ts): normalizer · Shared column handling and transformation helpers for tabular inputs. · `src/columnUtils.ts`
- [Report model](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportModel.ts): schema · Defines the normalized in-memory shape consumed by rendering. · `src/reportModel.ts`
- [Report generator](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/reportGenerator.ts): assembler · Composes validated inputs and parsed metrics into report-ready structures. · `src/reportGenerator.ts`

### Templates & output

HTML templates and asset embedding used to render final reports.

- [Embed assets](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/embedAssets.ts): packager · Inlines or packages assets for portable HTML output. · `src/embedAssets.ts`
- [Templates](https://github.com/yashsolanki466-hash/bestreport/blob/main/templates/report_full.ejs): html/ejs views · Presentation templates for full, interim, original, and other report variants. · `templates/report_full.ejs`
- [HTML shell](https://github.com/yashsolanki466-hash/bestreport/blob/main/templates/report_template.html): html template · Raw HTML template used for standalone report rendering. · `templates/report_template.html`

### Automation

Command-line, batch, and watch entry points.

- [Batch mode](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/batch.ts): orchestrator · Scans a root directory and generates reports for multiple projects. · `src/batch.ts`
- [CLI](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/cli.ts): entrypoint · Single-project command-line entry point for report generation. · `src/cli.ts`
- [Watch mode](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/watch.ts): polling runner · Triggers generation when a project folder becomes ready. · `src/watch.ts`

### Browser UI

React/Vite surfaces for previewing or interacting with report content.

- [Main app](https://github.com/yashsolanki466-hash/bestreport/blob/main/src/main.tsx): react app · Primary browser-facing Vite/React application for previewing report content. · `src/main.tsx`
- [App shell](https://github.com/yashsolanki466-hash/bestreport/blob/main/App.tsx): react shell · Top-level React shell for the browser UI. · `App.tsx`
- [Interim app](https://github.com/yashsolanki466-hash/bestreport/blob/main/interim_app/App.tsx): vite app · Separate lightweight Vite app for the interim report format. · `interim_app/App.tsx`

## Connections

- config.yaml → Config load: runtime config · Supplies repository-level settings.
- Default snippets → Report generator: snippets · Provides reusable snippet defaults for report assembly.
- Static content → Report generator: content · Feeds static report text and sections.
- Config load → Paths: settings · Configures path resolution and discovery rules.
- Paths → Validate: expected layout · Defines the project structure to check.
- Validate → Discover stats: ready tree · Only validated projects proceed to discovery.
- Discover stats → Data parser: discovered inputs · Selects which extracted files and tables to parse.
- Discover stats → GTF parser: annotation inputs · Routes annotation files into the GTF parser.
- Discover stats → FASTA stats: sequence inputs · Routes FASTA-derived inputs into sequence metrics extraction.
- Data parser → Column utils: tabular shape · Uses shared helpers to normalize columns and records.
- GTF parser → Report model: annotation data · Contributes parsed annotation structures to the model.
- FASTA stats → Report model: assembly stats · Contributes sequence and assembly metrics to the model.
- Data parser → Report model: normalized metrics · Provides standardized metrics and tables.
- Report model → Report generator: schema · Defines the structure used to compose the final report.
- Config load → Report generator: metadata · Supplies project metadata overrides and report options.
- Report generator → Templates: render data · Feeds the template layer with complete report content.
- Report generator → HTML shell: html data · Supports standalone HTML report generation.
- Templates → Embed assets: assets · Templates are packaged with inlined or embedded assets.
- HTML shell → Embed assets: assets · Static HTML output is prepared for portable delivery.
- CLI → Report generator: single project · Entry point for generating one report.
- Batch mode → Validate: multi-project scan · Discovers and checks many project roots.
- Watch mode → Validate: ready check · Polls until the input folder satisfies generation conditions.
- Main app → App shell: ui shell · Browser entry mounts the main application shell.
- Interim app → Templates: interim UI · Separate app aligns with interim report presentation.