Building a Blueprint

A blueprint is the foundational document that captures a customer's business domain in enough depth to drive software design, AI development, and ongoing maintenance. It is built through a series of structured interviews rather than document review — interviews yield richer, more nuanced information and surface context that written documentation rarely contains.

Why interviews, not documents

Reading existing documentation produces a surface-level understanding. Recorded interviews allow the interviewer to probe, clarify, and follow threads. The recording also becomes a reference that can be revisited as the blueprint evolves.

Conduct interviews across business, product, and technical dimensions. Multiple sessions are normal — do not try to capture everything in one sitting.

What a blueprint captures

A blueprint is organised around four types of content:

1. Business Concepts

The core vocabulary and domain model of the business. These are the entities, terms, and relationships that business users think and speak in — customers, orders, cases, assets, whatever is native to their world. Capturing these precisely matters because they become the language of the codebase.

2. Stories

The jobs that users do — both now and as envisioned in the software. Stories describe what people need to accomplish, not how the system implements it. They may currently be done in spreadsheets, email, or manual processes. That is fine. The goal is to understand the work, not assume it is already digital. Stories become the features the software will deliver.

3. Resources

The technical landscape the software will operate within. This includes third-party systems, data sources, APIs, integrations, and infrastructure that the application must connect to or work alongside. Resources define the boundaries and integration points of the solution.

4. Hacks

Known solutions, proven patterns, and established ways of thinking that apply to this domain. "Hack" is used in the positive sense — these are solved problems. Capturing them early prevents reinvention and helps the development team apply the right patterns from the start.

Building a blueprint from source code

When a customer has an existing system — particularly a legacy application — the blueprint can be built partly through code analysis rather than interviews alone. This is particularly valuable when documentation doesn't exist or the people who built the system are no longer available.

The process works as follows:

1. Access the codebase — Telos signs an NDA and receives a copy of the source code. It is used solely for analysis purposes.
2. Software walkthrough — Before running any analysis, a walkthrough of the live software (1–4 hours depending on complexity) gives the AI a frame of reference: the language, the information architecture, and the user flows. This significantly improves analysis quality.
3. Analysis tickets — Rather than pointing AI at the entire codebase, Telos plans a set of discrete analysis tickets — one per module, function, or domain area. Each ticket is executed independently, extracting what that part of the code does and why, separated from implementation detail.
4. AI cost — Deep code analysis consumes AI tokens at scale. A thorough analysis of a large legacy system may cost $1,000–$2,000 in AI consumption. This is a one-time cost and is factored into the initial engagement.
5. Subject matter interviews — Code analysis is complemented by interviews with people who know where the skeletons are: the original developers, long-tenured staff, or domain experts. These conversations surface context that no amount of code reading can reveal.
6. Blueprint output — The result is a structured blueprint covering business concepts, stories, resources, and hacks — an AI-consumable knowledge base that also serves as the foundation for human-readable documentation and executive-level artefacts.

Note on obscure languages: AI tools are less proficient with older or proprietary languages (e.g. Progress, COBOL). Analysis scripts should be tuned in advance to guide the AI on what to look for, and human experts should be available to interpret ambiguous findings.

The blueprint as a living document

The blueprint is not a one-time deliverable. As development progresses, the blueprint is maintained and enriched. It becomes an increasingly detailed record of how the software works, why decisions were made, and what the domain means. This makes it a primary source of intellectual property for the customer and a key input for AI-assisted development and maintenance.

See TEL302 for how the blueprint is used in the software development process.