Intellica Training
Architecture documentation that people and AI can act on.
arc42 is a free, open template for documenting software architecture. One hands-on day to write yours, for engineers at every level.
Led by Damian Ramsajan, solution architect and workshop facilitator, founder of Intellica AI.
- Date
- Saturday 30 January 2027
- Time
- 9:00 am to 5:00 pm
- Place
- UWI St Augustine
- Format
- In person, in teams of 3 to 4
- Price
- TT$999 per person. Full day, all materials.Early-bird price TT$999 until 30 November 2026.
- 1 day
- Saturday 30 January
- 12 sections
- drafted for your own system
- In person
- UWI St Augustine
- Teams of 3 to 4
- working on a real system
01The template
Twelve sections, twelve questions
arc42 gives each kind of architecture information one place to live. By the end of the day you will have answered every one of these for your own system.
- 1Introduction and goalsWhy does it exist, and what matters most?
- 2ConstraintsWhat can’t we change?
- 3Context and scopeWho do we talk to?
- 4Solution strategyWhat is our approach?
- 5Building blocksWhat are the parts?
- 6RuntimeHow do the parts interact?
- 7DeploymentWhere does it run?
- 8Crosscutting conceptsWhat recurs everywhere?
- 9DecisionsWhy this choice?
- 10Quality requirementsHow good, measurably?
- 11Risks and debtWhat could go wrong?
- 12GlossaryWhat do the words mean?
02Why now
What arc42 is, and why it matters now
AI tools can generate code, but they can’t read your intent. Documentation that records goals, contracts and decisions is how you hand it over.
What it is
arc42 is a free, open template for documenting software and system architecture. Its twelve sections give each kind of architecture information a clear place: goals and constraints, context, building blocks, runtime behaviour, deployment, crosscutting concepts, decisions, quality scenarios, risks and a glossary.
It is a structure, not a method, and it doesn’t care about notation: Markdown, text-based diagrams or UML all work. It fits well as docs-as-code, kept in the repository and reviewed like source.
It is free to use, even commercially, with credit to its creators, Gernot Starke and Peter Hruschka.
Why it matters now
Teams lose context. People leave, systems grow and decisions fade. A consistent structure makes the why findable.
AI tools only know what is written. Coding agents generate code quickly but guess at intent. Goals, contracts and recorded decisions are how you give it to them.
Specifying and checking are gaining value. As more code is generated, stating what good looks like and verifying the result become the scarcer skills.
03How it helps
Pick what you want to do
We show how arc42 gets you there, what you do in the workshop, and what to expect, including where it will not help.
Spend less on AICut wasted tokens
AI coding tools start every session knowing nothing about your project. Without a written map they read lots of files and guess, and you pay for every token. A short, accurate architecture note (what the parts are, what each promises, what you decided and why) gives them what the code can’t tell.
In the workshop. You write the short version: a strategy table, block descriptions, one contract and one decision record. Then you test it with a prompt template and a simple three-way experiment.
Be realistic. The evidence is mixed. A February 2026 ETH Zurich study reported that long, auto-generated context files lowered success and raised cost by over 20%. So the aim is short, human-written and specific, not more. Test it on your own tasks.
Build at workBuild systems and integrations with fewer surprises
Most integration trouble hides at the edges: who talks to whom, in what format, and what happens when it fails. arc42 gives you a context view, interface contracts, failure scenarios and decision records, so colleagues and vendors work from the same picture.
In the workshop. You draw the context and Level-1 views, write a contract with error modes, and trace one runtime scenario with a failure branch.
Be realistic. It won’t design the system for you. It makes your design visible so it can be questioned before it is expensive to change.
Start somethingTurn an idea into a brief anyone can build from
Founders and freelancers need to explain an idea to developers, clients and AI tools without it being misread. Quality goals, constraints such as budget, team and deadline, and a context view turn a vague idea into something others can build, price and challenge.
In the workshop. Use your own idea as the workshop case if you like. You leave with goals, constraints, a context view and a list of risks.
Be realistic. A document doesn’t prove people will pay. Use it to sharpen the idea, then test the market.
Ride the AI waveBuild the skills AI makes more valuable
As AI writes more of the code, the scarce skills move towards deciding structure, stating what good looks like, spotting AI’s mistakes and recording why. Those are the skills this workshop practises.
In the workshop. In the AI lab, AI drafts sections from your notes, then your team red-teams the result and decides what to keep.
Be realistic. This builds skill, not a job guarantee. You practise judging AI output, which stays useful whatever tools change.
04The cost of not writing it down
What goes wrong without it
Knowledge lives in heads
Newcomers wait for someone to explain how things fit together.
Decisions get forgotten
Teams re-debate old choices, or break them by accident.
Qualities stay vague
“Fast” and “secure” mean different things to different people.
Machines read it too
AI tools act on what is written and guess what isn’t.
05Outcomes
What you will be able to do
Set the goals
Identify stakeholders and write quality goals with numbers instead of adjectives.
Draw the system
Sketch a context view and a Level-1 building-block view, then write one component contract.
Show behaviour
Describe a runtime scenario with a failure branch, and a deployment view.
Record why
Write an architecture decision record (ADR) that lists the road not taken.
Work with AI
Let AI draft a section, then find and fix its mistakes.
Write for agents
Shape documentation so both people and coding agents can use it.
06The programme
The day, hour by hour
Thirteen short parts. Each part has a finished example and then your turn. You build one document across the day: your own arc42 skeleton, section by section, for a real system your team knows.
Morning: foundations to strategy
Opening
Why architecture goes undocumented, how we will learn, and the rules for using AI today. Form teams, choose your system and set up your tools, then take a short baseline quiz you will retake at the end.
You leave with: a team, a case and a working arc42 file
Foundations
What architecture is, why it is a set of trade-offs, and what good documentation is not. Stakeholders and concerns, views, the C4 zoom levels, and the twelve arc42 sections. A quick Markdown and Mermaid warm-up.
Warm-up exercise
- Break, 15 minutes
Section 1: goals, quality and stakeholders
Write a requirements overview that names no technology, then turn vague qualities like “fast” and “secure” into scenarios with numbers. Find the stakeholders and what each expects.
Exercise 1 · one page, peer reviewed
Section 2: constraints
Sort constraints from decisions from requirements with the three-question test, then write your own numbered constraints.
Exercise 2 · numbered constraints
Section 3: context and scope
Treat your system as a black box. Draw the business context, then record the technical channels in an interface table.
Exercise 3 · context diagram and table
Section 4: solution strategy
Turn each quality goal into an approach, a reason and the trade-off you accept. A neighbour reads only your table and guesses your architecture.
Exercise 4 · strategy table
- Lunch, 45 minutes
Afternoon: structure, behaviour and decisions
Section 5: building blocks
Split the system into five to nine blocks, name their responsibilities and interfaces, then write a contract with pre-conditions, post-conditions, invariants and error modes for your riskiest block.
Exercises 5a and 5b · Level-1 view and one contract
Sections 6 to 8: runtime, deployment, crosscutting
Draw one scenario as a sequence diagram with a failure branch, map every block to where it runs, and name the rules that recur across blocks.
Exercises 6, 7 and 8
- Break, 15 minutes
Section 9: decisions
Write an architecture decision record with real alternatives and at least one honest negative consequence, so a new teammate understands why not the other option.
Exercise 9 · one ADR
Sections 10 to 12: quality, risks, glossary
Grow your quality tree with a change scenario and a failure scenario, then list risks with mitigations and owners, and define your terms once.
Exercises 10 and 11
Late afternoon: AI and agents
AI lab
Have an assistant draft sections from your notes. Then red-team the result for ignored instructions, contradictions between sections and unsupported claims, and repair it, giving every AI line a verdict.
Exercise 12 · red-teamed AI draft
Agents as readers
What humans and coding agents each need from documentation: short indexes, contracts, stable IDs and reasons. Turn an invariant into a test, and see how to check the effect on your own work.
Close
Check your skeleton against a checklist, walk the gallery, retake the quiz, rate your own progress and leave with a 30-day plan.
You leave with: a complete first-draft arc42
07Take-home
You leave with
A complete skeleton
All twelve arc42 sections drafted for your own system.
Reusable pieces
A contract, an ADR and measurable quality scenarios you can copy into real work.
A repeatable method
An AI prompt template, a red-team checklist and a 30-day plan.
08Method
How you will learn
The day is built on how people pick up a new skill: see it done, try it yourself, then check your work with someone else.
See it done
For every section, a finished example from a real-world app, so you know what good looks like before you start.
Do it yourself
Early exercises are mostly filled in. Later ones give you only a template, then a blank page, so the support fades as you grow.
Check with peers
Swap drafts with another team using a short checklist, and retake the opening quiz at the end to see your own progress.
09Audience
Who it’s for
New to architecture documentation. Every section starts with a finished example and early exercises are mostly filled in. If you can explain how an app works, you can follow along. No UML needed.
Senior engineers, tech leads and architects. Go beyond the template: write quality scenarios with measurable response targets, interface contracts with invariants and error modes, and decision records that capture the road not taken. Then make the result useful to coding agents and keep it from drifting.
Analysts, testers, managers and founders who need one shared picture between the business and the build.
Already fluent in arc42? Expect a quick pass through the template, with the depth in contracts, quality scenarios, the AI lab and agent-readable documentation.
10Your facilitator
Damian Ramsajan
Solution architect and workshop facilitator, founder of Intellica AI
Also written Damain P. Ramsajan
- 30+ years in ICT
- Workshop facilitator for decades
- Former computer science lecturer
- Caribbean-wide implementations
- MSc, Strategic Business IT (Portsmouth)
- PGDip, Software Engineering (Aston)
Damian has spent three decades turning complicated software and process ideas into things teams can actually use. As a solution architect he has worked across Oracle, IBM, Microsoft, EMC, HP, Cisco and NetApp platforms on major system implementations throughout the Caribbean, and he has been explaining difficult concepts in workshops for decades, including three years lecturing computer science in the mid-2000s. Today he runs Intellica AI, designing and operating production AI systems documented with arc42, C4 and architecture decision records, so that any team can pick up the build on day one.
Seats are open for 30 January 2027
Early-bird price TT$999 until 30 November 2026.
11Questions
Questions
What is arc42?
A free, open template with twelve sections for writing down how a software system is built and why. It was created by Gernot Starke and Peter Hruschka.
Is this the official arc42 training?
No. This is an independent workshop built on the free arc42 template. It is not affiliated with or endorsed by arc42, and it does not lead to a certification.
I’m an experienced engineer. What’s in it for me?
The template is the easy part. The depth is in measurable quality scenarios, contracts with invariants and error modes, decision records with real alternatives, an AI lab where you red-team generated documentation, and designing docs that coding agents can use without drifting.
I’m new to this. Will I keep up?
Yes. Every section starts with a finished example, early exercises are mostly filled in, and you work in a team. The support fades as you gain confidence.
Will this really cut my AI costs?
It can, if you keep the documentation short and specific. Evidence so far is mixed, and long auto-generated context files can make things worse. The workshop shows you how to test the effect on your own work.
Where and when?
Saturday 30 January 2027, 9:00 am to 5:00 pm at UWI St Augustine. Registered participants get the exact room by email before the day.
Do I need to know UML?
No. Boxes, arrows and plain words are enough.
Which system do we document?
One your team can explain from memory, such as a school library, a clinic booking system or a maxi-taxi tracker. Please don’t share confidential details.
Will we use AI?
Yes, but you write the first draft yourselves. Then you use AI to find gaps, and you check every line it produces.
What should I bring?
A laptop with a Markdown editor that previews Mermaid diagrams, or a shared document your team can edit.
Is it a certification?
No. It is a practical workshop that ends with a document you can use.