How yashsolanki466-hash/bestreport works
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: reportGenerator.ts Report generator · statsDiscovery.ts Discover stats · validate.ts Validate · reportModel.ts Report model
Components 22
Inputs & config
Project folders, metadata, and static configuration that feed the generator.
- config.yaml · Primary repository-level configuration for report generation.
config.yaml - Default snippets · Shared snippet defaults used when assembling report text and content.
config/default_snippets.json - Static content · Repository-provided static report content overrides and defaults.
report_static_content.json
Core pipeline
Discovery, parsing, modeling, and report assembly.
- Paths · Resolves expected project directories and file locations.
src/paths.ts - Validate · Checks project layout, file presence, and readiness conditions.
src/validate.ts - Discover stats · Detects available data products and report inputs in the project tree.
src/statsDiscovery.ts - Config load · Loads and merges runtime configuration and project metadata.
src/config.ts - Data parser · Normalizes report tables and extracted metrics into structured data.
src/dataParser.ts - GTF parser · Extracts annotation features from GTF inputs.
src/gtfParser.ts - FASTA stats · Derives assembly and sequence metrics from FASTA-derived inputs.
src/fastaStats.ts - Column utils · Shared column handling and transformation helpers for tabular inputs.
src/columnUtils.ts - Report model · Defines the normalized in-memory shape consumed by rendering.
src/reportModel.ts - Report generator · 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 · Inlines or packages assets for portable HTML output.
src/embedAssets.ts - Templates · Presentation templates for full, interim, original, and other report variants.
templates/report_full.ejs - HTML shell · Raw HTML template used for standalone report rendering.
templates/report_template.html
Automation
Command-line, batch, and watch entry points.
- Batch mode · Scans a root directory and generates reports for multiple projects.
src/batch.ts - CLI · Single-project command-line entry point for report generation.
src/cli.ts - Watch mode · 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 · Primary browser-facing Vite/React application for previewing report content.
src/main.tsx - App shell · Top-level React shell for the browser UI.
App.tsx - Interim app · Separate lightweight Vite app for the interim report format.
interim_app/App.tsx
Connections 24
- 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.