The Technical Narrative: Documenting Your Pipeline for Assessment

Module 5, Unit 4 | Lesson 3 of 3

By the end of this lesson, you will be able to:

• Write a structured technical narrative that explains every design decision in your pipeline (K11, K12, S10, S11, B6)
• Map each major decision to the specific KSBs it evidences (K11, K12, S10, S11, B6)
• Produce a portfolio submission package with a clear folder structure that assessors can navigate (S10, B6)
• Explain trade-offs rather than just describing what you built (K11, K12, S11, B6)

Your pipeline works. It ingests, validates, classifies, routes, approves, and outputs — with structured logging, dual-model inference, retry logic, and a connector interface. The code is done.

The portfolio narrative is where you prove you understand it.

An assessor reading your code will see what you built. The narrative tells them why — why you chose Pydantic over manual validation, why you used an abstract base class for connectors, why PII records go to a local model, why the retry backoff is exponential rather than fixed. The decisions that look obvious after building them need to be explained as if you are explaining them to someone seeing the pipeline for the first time.

🔑 Key term — Technical narrative: A structured document that explains the architecture, design decisions, and trade-offs of a system you built. Unlike code comments (which describe what code does), a technical narrative describes why those choices were made, what alternatives were considered, and what the consequences of those decisions are.

Structure of the technical narrative

Write a document with the following sections. Each section should be 3–6 paragraphs of prose — not bullet points.

1. Problem and context (400–600 words)

Describe the problem your pipeline solves. What is the AI Tool Usage Log? What are its quality problems? Why does an automated pipeline add value compared to manual processing? What happens if a PII-flagged record is routed incorrectly?

Do not just describe the dataset. Describe why the problem is non-trivial — why it required a multi-stage pipeline rather than a single script.

Or write this section about your own organisation instead. If there is a dataset your team actually maintains that has the same shape — an export, a log, a spreadsheet someone keeps by hand — describe that problem here and use the AI Tool Usage Log as the worked example you built to understand it. You are not being asked to build a second pipeline; you are being asked to say what this one would have to become to run against real data you are responsible for. Which fields would need validators, where the halt threshold would sit and who would own it, which records could not be sent to a cloud API, and who gets told when it stops. The closing question in L1.3 and the optional prompts at the end of L2.3, L3.3 and L4.2 are exactly this material — if you answered them as you went, this section is mostly written. Assessors consistently find this version stronger, because it evidences judgement about a real context rather than comprehension of a supplied one.

2. Architecture overview (400–600 words)

Describe the six-stage pipeline at a high level. Explain the flow of data from CSV ingestion through to JSON output. Explain what PipelineState is and why it exists (why not pass data between stage functions as arguments?). Explain the StageResult pattern.

Include a diagram — even a simple ASCII art or hand-drawn flowchart showing the stages and the queues.

3. Key design decisions (600–900 words)

This is the most important section. For each of the following decisions, explain what you chose, what the alternative was, and why you made the choice you did:

• Pydantic for validation: Why use a schema library rather than writing if row["quality_score"] is None manually?
• Abstract base class for connectors: Why define an interface rather than two separate functions?
• Dual-model inference: Why use Ollama locally for PII records rather than anonymising before sending to OpenAI?
• Exponential backoff with jitter: Why not just retry immediately? Why add jitter?
• Structured logging over print: What capability does JSONL logging provide that print does not?
• Human approval checkpoint: Why build it into the pipeline stage architecture rather than as a post-processing step?

Here is what the difference looks like on a second decision, so you have two models to work from rather than one.

Weak — describes the feature:

I used an abstract base class for the connectors. This is a good object-oriented design pattern and it means the connectors all have the same methods. I implemented JSONFileConnector and WebhookConnector.

Everything there is true, and none of it tells the assessor anything they could not get from reading the file. There is no alternative considered and no consequence named.

Strong — names the alternative and the consequence:

The obvious implementation was two functions, write_to_file() and write_to_webhook(), with stage_output choosing between them on a config flag. I used an abstract base class instead, because the @abstractmethod on health_check() makes the halt-on-unreachable-destination behaviour a property of the interface rather than of each implementation. With the two-function version, adding a third destination later means remembering to add its health check and remembering to add a branch to stage_output — two chances to introduce a silent failure where output is written without ever being verified. With the ABC, a connector that omits health_check() cannot be instantiated at all: the error surfaces at import, not in production. The cost is a small amount of ceremony for the two connectors I actually have, which I judged worth paying because the halt behaviour is the thing protecting against partial writes to a downstream system.

Notice the shape: what I could have done, what I did, the specific failure the choice prevents, and an honest note on what it cost. Every paragraph in section 3 should have those four parts. If you cannot name what the alternative was, you have not yet made a decision — you have followed an instruction, and the narrative is where that shows.

Coach Cora

The difference between a weak narrative and a strong one is specificity about trade-offs. "I used Pydantic because it is good for validation" is weak. "I used Pydantic because it lets me centralise all validation rules in one class, making them testable and auditable — if I had written per-field if statements scattered across the ingest and validate stages, adding a new rule or changing an existing one would require searching the entire codebase" is strong. Every design decision has a reason. Write the reason.

4. Testing and verification (300–400 words)

Describe the unit tests you wrote (L2.1), the isolation testing you used for debugging (L3.5), and the end-to-end verification steps from L4.1. Explain what each layer of testing catches that the others do not.

5. Performance and cost (300–400 words)

Describe your stage duration profile (L4.2). Identify the bottleneck and explain what you did to address it: the max_workers tuning, the classification cache. Include your actual measurements — real numbers are more convincing than theoretical claims.

6. What you would do differently (200–300 words)

A strong portfolio piece acknowledges limitations. What would you change if you were building this for a real production environment?

• The input() approval checkpoint would be replaced with a webhook-triggered async flow
• The file-backed classifier cache would be replaced with a Redis cache to handle concurrent runs
• The schema would be versioned so new data formats do not require code changes
• The logs/ directory would be replaced with a centralised log aggregator

These reflections show that you understand the gap between a portfolio project and a production system — and that you have thought through what that gap means.

Curious Cat

Why include a "what you would do differently" section? Because assessors are not just evaluating whether you completed the task — they are evaluating whether you understand software engineering trade-offs. A developer who cannot identify the limitations of their own work is a developer who cannot improve it. Identifying what you would change, and why, is evidence of exactly the reflective professional practice that apprenticeship standards ask for.

KSB mapping table

Include this table in your submission. For each KSB your module is assessed on, cite the specific component of your pipeline that evidences it:

Use this as a starting point, not a script. The evidence column should name your decisions — including the ones where you diverged from the lesson. An assessor can tell the difference between a table copied from the module and a table written by someone describing their own build.

Portfolio submission package structure

Organise your submission as follows:

portfolio_submission/
├─ technical_narrative.docx (or .pdf)
├─ pipeline/
│   ├─ schema.py
│   ├─ contracts.py
│   ├─ stages.py
│   ├─ classification_contract.py
│   ├─ classifier.py
│   ├─ local_classifier.py
│   ├─ connectors.py
│   ├─ pipeline_logger.py
│   ├─ classifier_cache.py
│   ├─ pipeline.py
│   ├─ test_workflow.py
│   ├─ requirements.txt
│   ├─ .env.example                 (variable names only — never the real key)
│   └─ .gitignore
├─ data/
│   └─ ai_tool_usage_log.csv
├─ artefacts/
│   ├─ data_profile.json            (L1.1 — where every design decision starts)
│   └─ clean_records.json           (L1.2 — the validated, normalised dataset)
├─ outputs/
│   ├─ pipeline_output.json         (from a successful run)
│   └─ logs/
│       └─ pipeline_abc12345.jsonl  (from the same run)
└─ README.md                        (setup and run instructions)

Three things people leave out, all of which cost marks:

The artefacts folder. data_profile.json is the document every later decision traces back to — the schema exists because of what the profile found. Submitting the pipeline without it means an assessor reads your validators with no evidence of why those rules and not others.

.env.example. Ship the variable names with empty values (OPENAI_API_KEY=) so a reader knows what configuration the project needs. Never ship the file with a real key in it. Check your submission for credentials before you zip it — this is the single most common way an apprentice accidentally leaks one.

A matched pair of outputs. pipeline_output.json and the JSONL log must come from the same run — check the run_id matches. A mismatched pair is worse than one file, because an assessor tracing a record across the two will find inconsistencies that look like bugs in your pipeline.

The README.md should include: Python version, how to create the virtual environment and install from requirements.txt, how to set up the .env file, how to install and start Ollama, and how to run the pipeline. Write it for someone who has never seen the project — then test it by following your own instructions in a fresh folder.

Build activity

1. Write section 1 (Problem and context) — at least 400 words explaining the problem and why it requires a pipeline. Write it about the AI Tool Usage Log, or about an equivalent dataset your own organisation maintains, using the module's case as your worked example.
2. Write section 2 (Architecture overview) — draw your pipeline diagram, even if it is hand-drawn and photographed.
3. Write section 3 (Key design decisions) — one paragraph per decision, explaining the alternative and the reason for your choice.
4. Complete sections 4, 5, and 6 using your actual test results and stage duration numbers.
5. Assemble the KSB mapping table using the examples above as a starting point.
6. Organise the submission package folder structure and verify all files are present.

Challenge Chase

Your technical narrative describes the pipeline you built. Now write a short technical proposal (one page) for the next iteration: a streaming version of this pipeline that processes records as they arrive in real time, rather than as a batch. What would change in the architecture? Which stages would need redesign? What new failure modes would appear? How would you handle the human approval checkpoint if records arrive continuously rather than in a batch of 30?

The code from this lesson

The finished pipeline, which is what your submission pack contains. No new code in this lesson — this is the L4.2 state, packaged so you can check yours against it.

Take it if you would rather read and run the code than type it out. Typing it is still the better way to learn it — this is here so a typo cannot cost you the lesson.

Checklist

• Technical narrative includes all six sections with specific, trade-off-focused explanations
• Every design decision in section 3 explains what the alternative was and why you chose what you did
• Section 5 includes real measured stage durations and benchmark results
• Section 6 identifies at least three specific production improvements with reasons
• KSB mapping table is complete with pipeline-specific evidence for each KSB
• Submission package folder structure is organised and all files are present
• README.md explains how to install, configure, and run the pipeline from scratch

Quick Check

KSB evidence focus

• K11 — Understands relevant data governance, data privacy and security issues. The technical narrative section on dual-model routing and the human approval checkpoint is your primary K11 evidence. The explanation needs to show that you understood the governance requirement — not just that you implemented a feature that happened to address it.

• B6 — Shows curiosity and initiative. The "what you would do differently" section and the Challenge Chase streaming proposal are the clearest B6 evidence in the module. Identifying limitations and imagining the next iteration without being asked to do so is precisely what this behaviour statement describes.

Well done. You have built a complete, production-structured AI data pipeline — from raw messy CSV input through schema validation, LLM-powered classification, conditional routing, governance checkpoints, structured logging, and optimised output. The technical narrative you write now is the evidence that you understood every decision you made. That understanding is the module.