Narrative

README.Rmd

@@ -31,111 +31,181 @@ Sys.time()
 
 ---
 
-
 ## Overview
 
-The project attempts to build a framework for turning single-case data processing scripts into **scalable, repeatable batch workflows**.
+`genprocShiny` is a Shiny proof of concept for turning a **single working data-processing task** into a **batch process over many explicit input/output cases**.
+
+The concrete idea is simple:
+
+- you already know how to perform one transformation;
+- you now need to run that transformation across many files, datasets, or parameterized cases;
+- you want a structured way to define the cases, validate the function, run the process, and recover execution logs.
 
-It enables you to apply a function across many cases defined in a table, while ensuring **traceability, robustness, and operational control**.
+In this PoC, the process is driven by a **mask**: a table in which each row defines one task to execute.
 
-This is the Shiny implementation inherent to the project.  
-
 ---
 
-## Installation
+## The concrete problem this project targets
 
-You can install the development version with:
+A common practical situation is the following:
 
-```{r, eval = FALSE}
-devtools::install_github("danielrak/genprocShiny")
-```
+1. you successfully transform one input into one output;
+2. you realize that the same operation must now be repeated dozens or hundreds of times;
+3. each case has explicit inputs and outputs;
+4. you need something more robust than copying code or writing an ad hoc loop.
+
+For example:
+
+- convert many files from one format to another;
+- apply the same cleaning function to many datasets;
+- generate many outputs whose paths are already listed in a control table;
+- run a repeatable administrative or statistical transformation over many declared cases.
+
+This is the concrete narrative of `genprocShiny`: **scale input/output tasks from one validated transformation**.
+
+---
+
+## What the current PoC already does
+
+The current app is intentionally minimal, but it already covers the full logic of a batch run:
+
+- **upload a mask** that declares the cases to run;
+- **build a function from example code** or write the function directly;
+- **map function arguments to mask column names**;
+- **launch execution**;
+- **retrieve row-wise logs** describing success or failure.
+
+This means the app is not just about iterating over rows. It is about making a transformation **operational**:
+
+- the cases are explicit;
+- the interface between function and task table is explicit;
+- execution is separated from result inspection;
+- logging is part of the workflow.
+
+---
+
+## Why this is not only a wrapper around `purrr`
+
+Iteration tools are useful, but they do not by themselves define an execution framework.
+
+`genprocShiny` adds several layers around the actual iteration step:
+
+- a **mask-first** way to declare tasks;
+- a **function-to-mask interface** through argument mapping;
+- a **from-example-to-function** step for users who can demonstrate one task but do not want to parameterize everything by hand;
+- **row-wise success/error logging**;
+- **background execution** and parallel processing support.
+
+The goal is therefore not only to "map a function" but to help turn one transformation into a **repeatable batch process with observable execution**.
 
 ---
 
-## A demo vignette
+## Installation
+
+You can install the development version with:
 
 ```{r, eval = FALSE}
-vignette("genprocShiny", "genprocShiny")
+devtools::install_github("danielrak/genprocShiny", build_vignettes = TRUE)
 ```
 
 ---
 
-## Why?
+## Main entry points
 
-In many real-world workflows, processing starts from a single case:
+Launch the Shiny application with:
 
-- one file  
-- one dataset  
-- one transformation  
+```{r, eval = FALSE}
+genprocShiny::run_app()
+```
 
-Scaling this often leads to:
+Create a demo framework oriented toward repeated file processing with:
 
-- duplicated code  
-- fragile loops  
-- limited error handling  
-- no visibility on execution  
+```{r, eval = FALSE}
+genprocShiny::create_demo_framework("path/to/your/folder")
+```
 
-While tools like `purrr::pmap()` help iterate, they do not address **operational concerns**.
+Browse available vignettes with:
 
-**genproc goes beyond iteration by structuring execution.**
+```{r, eval = FALSE}
+browseVignettes("genprocShiny")
+```
 
 ---
 
-## General features
+## A more concrete example of use
 
-- **Standardized execution**  
-  Functions are adapted to a consistent interface.
+Suppose you have one working transformation that turns one input file into one output file.
 
-- **Flexible parameter mapping**  
-  Decouples function logic from input data structure.
+You now want to run it on many cases.
 
-- **Execution robustness**  
-  Each run is isolated with controlled error handling.
+A typical workflow is:
 
-- **Traceable outputs**  
-  Structured logs for each execution (success, failure, inputs).
+1. prepare a mask with columns such as input path, input file, output path, and output file;
+2. define the transformation function;
+3. map the function arguments to the mask column names;
+4. run the process;
+5. inspect the resulting logs.
 
-- **Background and parallel execution**  
-  Runs independently from the interactive session.
+This is exactly the kind of use case the current PoC is designed to make more explicit and more reusable.
 
 ---
 
-## Typical use cases
+## From example to function
 
-- Batch processing of files or datasets  
-- Reproducible data preparation pipelines  
-- Administrative or production workflows  
-- Scaling a prototype script to industrial execution  
+One important part of the current PoC is that the function can be obtained in two ways:
+
+- **directly**, by writing the function code yourself;
+- **indirectly**, by starting from example code and transforming it into a function.
+
+This matters for a practical reason: many users know how to perform one transformation in R, but the step from "working example" to "reusable function" is often the first barrier to scaling.
+
+`genprocShiny` therefore includes a dedicated interface for building the function from example code and then validating or editing the resulting function before execution.
 
 ---
 
 ## Shiny interface
 
-You can launch the application with:
+The current interface is organized as four steps:
 
-```{r, eval = FALSE}
-genprocpoc::run_app()
-```
+1. **Mask**
+2. **Function**
+3. **Execution**
+4. **Results**
 
-The interface allows you to:
+This reflects the intended workflow of the PoC:
 
-- upload an input table  
-- define a processing function  
-- map parameters  
-- launch execution  
-- inspect results  
+- declare the tasks;
+- validate the transformation;
+- run the batch process;
+- inspect the logs.
 
 ---
 
-## What’s next
+## Current scope
+
+This repository should be read as a **proof of concept**.
 
-Planned enhancements include:
+Its value is not yet to cover every industrial case, but to make the core workflow tangible:
 
-- stronger input validation and safer code handling  
-- improved monitoring and real-time feedback  
-- incremental logging during execution  
-- more polished user interface  
-- configuration management for reproducibility  
-- more scalable execution strategies  
+- a task table;
+- a reusable function;
+- an explicit interface between both;
+- scalable execution;
+- and structured logs.
+
+That scope is narrower and more concrete than a general-purpose workflow platform, and that is deliberate.
 
 ---
+
+## What comes next
+
+Planned improvements include:
+
+- stronger validation of user inputs and code;
+- more informative logs, including richer execution metadata;
+- better live monitoring during execution;
+- easier editing and testing of functions and mappings;
+- improved user experience in the Shiny interface;
+- more robust support for broader classes of processing tasks.
+
+In other words, the current PoC already demonstrates the main idea, while the next iterations will make it safer, clearer, and more useful in real batch-processing contexts.