From 2e03521c93f63b3ed9d90ae2c4153321593cf77c Mon Sep 17 00:00:00 2001
From: Ravi <7014230+arelra@users.noreply.github.com>
Date: Wed, 15 Jan 2025 10:49:17 +0000
Subject: [PATCH] Doc explaining the codebase structure

---
 src/code-structure.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 src/code-structure.md

diff --git a/src/code-structure.md b/src/code-structure.md
new file mode 100644
index 000000000..525ea6b0f
--- /dev/null
+++ b/src/code-structure.md
@@ -0,0 +1,41 @@
+# Commercial codebase structure
+
+The entry point of the commercial runtime is [commercial.ts](./commercial.ts)
+
+The codebase is structured to align with the [lifecycle](https://github.com/guardian/commercial-playground/blob/main/simple-ad-example/render-ad.html) of displaying an advert
+
+The high level sequence is as follows:
+
+## init
+
+Initialise commercial, decide if we are running consented, consentless (i.e. opt out) and initialise respective modules
+
+In particular initialises Google Publisher Tag (GPT) in [prepare-googletag](./init/consented/prepare-googletag.ts)
+
+## define
+
+Call Google Publisher Tag (GPT) to _define_ an advert, with its size mappings
+
+## display
+
+Call Google Publisher Tag (GPT) to _display_ an advert
+
+Includes logic to control lazy loading and refresh
+
+## events
+
+Ad event handlers
+
+## insert
+
+Code that inserts all dynamic ads i.e. spacefinder inserted ads or inserted ads for specific use cases
+
+## experiments
+
+AB test modules
+
+## lib
+
+Library modules
+
+Exported library utilties are specified in [export.ts](./init/consented/export.ts)