Working on concepts documentation

docs/_media/algo_flow.drawio

@@ -0,0 +1 @@
+<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel>

docs/_media/algo_flow_01.drawio

@@ -0,0 +1,67 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36" version="24.8.6">
+  <diagram name="Page-1" id="HX-n5RwU4yS9j-6OuBTY">
+    <mxGraphModel dx="1006" dy="449" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-1" value="RawHits" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#4DB6AC;" vertex="1" parent="1">
+          <mxGeometry x="10" y="40" width="70" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-2" value="Hit Processing Algorithm" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FF8A65;" vertex="1" parent="1">
+          <mxGeometry x="110" y="25" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-3" value="HitClusters" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#4DB6AC;" vertex="1" parent="1">
+          <mxGeometry x="260" y="40" width="90" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-5" value="Track Finding&lt;div&gt;Algorithm&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FF8A65;" vertex="1" parent="1">
+          <mxGeometry x="370" y="25" width="100" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-6" value="Candidates" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#4DB6AC;" vertex="1" parent="1">
+          <mxGeometry x="500" y="40" width="80" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-8" value="Track Fitting&lt;div&gt;Algorithm&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#FF8A65;" vertex="1" parent="1">
+          <mxGeometry x="610" y="25" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-9" value="Tracks" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#4DB6AC;" vertex="1" parent="1">
+          <mxGeometry x="760" y="40" width="70" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-17" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="Q2nsGRmkFAV52NvcU29X-1" target="Q2nsGRmkFAV52NvcU29X-2">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="400" y="430" as="sourcePoint" />
+            <mxPoint x="450" y="380" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-18" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="230" y="54.5" as="sourcePoint" />
+            <mxPoint x="260" y="54.5" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-19" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="Q2nsGRmkFAV52NvcU29X-3" target="Q2nsGRmkFAV52NvcU29X-5">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="240" y="64.5" as="sourcePoint" />
+            <mxPoint x="270" y="64.5" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-20" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="Q2nsGRmkFAV52NvcU29X-5" target="Q2nsGRmkFAV52NvcU29X-6">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="250" y="74.5" as="sourcePoint" />
+            <mxPoint x="280" y="74.5" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-21" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="Q2nsGRmkFAV52NvcU29X-6" target="Q2nsGRmkFAV52NvcU29X-8">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="260" y="84.5" as="sourcePoint" />
+            <mxPoint x="290" y="84.5" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="Q2nsGRmkFAV52NvcU29X-22" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="Q2nsGRmkFAV52NvcU29X-8" target="Q2nsGRmkFAV52NvcU29X-9">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="270" y="94.5" as="sourcePoint" />
+            <mxPoint x="300" y="94.5" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docs/concepts.md

@@ -16,6 +16,118 @@ By assigning threads to arrows, JANA2 takes full advantage of modern hardware, a
 ![JANA2 Factory diagram](_media/concepts-factory-diagram.png)
 
 
+
+## Algorithms organization
+
+One can see the data analysis application flow as a chain of algorithms providing some data transformation from 
+what is given as application input and what is produced as an output. Some very simplified such chane is given on 
+the next diagram. 
+
+![Simple Algorithms Flow](_media/algo_flow_01.svg)
+
+Where for each event, raw ADC values of hits are taken, combined into clusters then put into track finding and
+fitting algorithms whith resulting tracks as the chain output. Experts would instantly spot, that such reconstruction
+chain in real life the graph would be much complex and much more elements are required: Geometry, Magnetic Field maps,
+calibrations and alignment, which will be covered later in the documentation.  We start with how the algorithms
+are implemented in JANA2, what is this data, that flows between the algorithms and how those algorithms may be wired together.
+
+### Algorithms
+
+### Declarative way
+
+JANA2 call those algorithms to calculate specific results on an event-by-event basis. 
+Algorithms are decoupled from one another. One can think of algorithms in declarative or imperative ways. JFactory supports both!
+
+### Data
+
+JANA2 alows users to define and select their own event models, 
+providing the flexibility to design data structures to specific experimental needs. Taking the above 
+diagram as an example, classes such as `RawHits`, `HitClusters`, ... `Tracks` might be just a user defined classes. 
+
+JANA2 offers extended support for PODIO (Plain Old Data Input/Output) to facilitate standardized data handling, 
+it does not mandate the use of PODIO or even ROOT. This ensures that users can choose the most suitable data management 
+tools for their projects without being constrained by the framework.
+
+
+
+
+
+
+
+
+```mermaid
+graph LR
+    A[RawHits]:::data --> B("Hit\nReconstruction\nAlgorithm"):::algorithm
+    B --> C[HitClusters]:::data
+    C --> D("Seeding\nAlgorithm"):::algorithm
+    D --> E[TrackCandidates]:::data
+    E --> F("Kalman\nFilter"):::algorithm
+    F --> G[Tracks]:::data
+
+    classDef data fill:#4DB6AC,stroke:#000,stroke-width:1px,color:#000
+    classDef algorithm fill:#FF8A65,stroke:#000,stroke-width:1px,color:#000
+```
+
+
+```mermaid
+graph LR
+
+%% Define classes for styling
+classDef data fill:#4DB6AC,stroke:#000,stroke-width:1px,color:#000
+classDef algorithm fill:#FF8A65,stroke:#000,stroke-width:1px,color:#000
+classDef eventsource fill:#FFD54F,stroke:#000,stroke-width:1px,color:#000
+classDef eventprocessor fill:#BA68C8,stroke:#000,stroke-width:1px,color:#000
+
+%% Event Source
+ES[EventSource]:::eventsource
+
+%% Algorithm Flow
+subgraph Algorithms
+    A[RawDataHit]:::data
+    B("Hit\nReconstruction\nAlgorithm"):::algorithm
+    C[TrackHitClusters]:::data
+    D("Seeding\nAlgorithm"):::algorithm
+    E[TrackCandidates]:::data
+    F("Kalman\nFilter"):::algorithm
+    G[Tracks Data]:::data
+
+    %% Define the flow between algorithms and data
+    A --> B
+    B --> C
+    C --> D
+    D --> E
+    E --> F
+    F --> G
+end
+
+%% Event Processors
+EP1[EventProcessor:\nWrite to Disk]:::eventprocessor
+EP2[EventProcessor:\nAnalysis]:::eventprocessor
+
+%% Connect EventSource and EventProcessors to the Algorithm Flow
+ES --> A
+G --> EP1
+G --> EP2
+```
+
+
+
+```mermaid
+block-beta
+  columns 3
+  a:3
+  block:group1:2
+    columns 2
+    h i j k
+  end
+  space
+  block:group2:3
+    %% columns auto (default)
+    l m n o p q r
+  end
+  
+  h-->r
+```
 ## JANA concepts
 
 - JObjects are data containers for specific resuts, e.g. clusters or tracks. They may be plain-old structs or they may