# Software archaeology — Genyra > Legacy code analysis: recover the architecture, dependencies, data flows and business rules inside COBOL, mainframe and Java systems nobody can fully explain. Canonical page: https://genyra.com/solutions/software-archaeology Recover the understanding your systems were built on. From COBOL cores to ageing Java estates, we trace the code, data, rules and dependencies behind software that still works but can no longer be explained, so it can be maintained, converted or replaced with evidence rather than guesswork. ## What software archaeology is. Software archaeology is the disciplined investigation of an existing system to recover the understanding it was built on: what it does, how it is structured, what it depends on and which of its behaviours carry decisions the organisation still relies on. It treats the code, data, configuration and operating history as evidence, and it produces documentation that did not exist before. Systems become difficult for ordinary reasons. The people who designed them move on. Years of urgent changes accumulate beside the original design. Documentation describes the first version, not the fifteenth. Vendors disappear, source is partly lost, and a scheduled job somebody wrote one evening becomes permanent. None of this means the system is bad. It means the knowledge has drifted away from the thing that runs. ## Recover dependencies and boundaries. The first product of an investigation is an honest map of what the system is. We inventory components, databases, scheduled jobs, interfaces to other systems, shared files, credentials and the infrastructure underneath them, and we record which of these the system cannot run without. The historical architecture matters as much as the current one. Knowing which parts were designed, which were bolted on and which were retired but never removed explains why the system behaves as it does and shows where a boundary can safely be drawn for a change. ## Discover the business logic. Validation, calculations, limits, approval steps and special cases often exist only in code. Some are policy. Some are the fossil of a problem solved in a particular year. We trace each rule to where it is enforced, work out what it protects and check the interpretation with the people who use the system. The result separates rules that must be preserved from implementation detail that can be let go. - Calculations and rounding conventions - Validation and eligibility rules - Approval paths and exception handling - Rules that live in data, not code ## Investigate interfaces and data flows. A task rarely stays inside one program. We follow it from the screen or message where it starts, through application logic and stored data, out to the services, files and reports it touches, recording where information is transformed and where its meaning quietly changes. Interfaces that other teams or organisations depend on are documented as contracts, because they are the first thing a migration breaks. ## Analyse only what you are authorised to analyse. Investigation is agreed before it starts. We work from the repositories, builds, binaries, documentation and environments you authorise us to examine, on terms that respect licences, contracts and data obligations. Where source is missing, authorised analysis of binaries, configurations and runtime behaviour can recover what the application does. Representative or redacted data is preferred; production access and any change to a system are separate decisions, never a by-product of looking at it. - Written scope of systems, artefacts and environments - Legal and licensing review before binary analysis - Data handling agreed with your security function - Read-only by default; changes are a separate authorisation ## Document what was never documented. Everything recovered is written down in a form the organisation can keep and maintain: architecture views, dependency records, traced workflows and a register of business rules, each tied to the evidence it came from. We distinguish clearly between what was observed, what is a well-supported explanation and what remains open, so that nobody later mistakes an assumption for a fact. - Observed: behaviour demonstrated in code, data or operation - Explained: a reading supported by evidence and confirmed with users - Open: a question that still needs an owner and an answer ## How an engagement is scoped. An archaeology engagement is sized around a question: what do we need to understand before we can safely change, integrate, migrate or retire this system? From that question we agree the systems in scope, the evidence available and the depth of recovery required. Work proceeds in four stages, and each stage produces something you can keep even if the engagement stops there. - Authorised evidence — Agree the systems, artefacts, environments and data-handling terms, and confirm what we may examine. - Inventory — Catalogue components, stores, jobs, interfaces and infrastructure, and establish the system boundary. - Traced workflows — Follow the tasks that matter through the layers, recovering rules, data meaning and dependencies as we go. - Findings and options — Report what was found with its evidence, and set out the preservation, migration or reconstruction options it supports. ## What you receive. Deliverables are agreed against the scope and the evidence available. A typical engagement produces some or all of the following, written for the engineers who will maintain the system and the people who have to make decisions about it. - Architecture assessment — Current and historical structure of the system, its boundary and the condition of each part. - Dependency inventory — Every component, store, job, service, file and interface the system relies on, with owners where known. - Technical findings report — Risks, defects, unsupported components and fragile areas, each tied to evidence and ranked by consequence. - Behavioural documentation — Traced workflows and a register of business rules, separating observed behaviour from assumptions. - Migration considerations — What must stay compatible, which interfaces are contracts, and how a change would be tested and proven. - Modernisation roadmap — Sequenced options for preserving, migrating or reconstructing parts of the system, with the trade-offs made explicit. ## Preserve, migrate or reconstruct. The findings decide the path, not the other way round. Sometimes the right outcome is to keep a working component and protect it properly. Sometimes it is to move it. Occasionally it is to rebuild it from the recovered rules. Most real systems need a mixture, decided part by part. Whichever path is chosen, the recovered documentation becomes the acceptance standard for it: the behaviours that must survive, the data that must keep its meaning and the interfaces that must not change. - Preserve — Keep the component as it is, document it, put it under test and contain its dependencies. Right when it works, the rules are sound and the cost of change outweighs the benefit. - Migrate — Move the behaviour to a supported platform while keeping the interfaces and data meaning intact. Right when the logic is worth keeping but the technology underneath is not. - Reconstruct — Re-implement from the recovered rules and workflows, dropping accidental complexity. Right when the original can no longer be safely changed and its purpose is now understood well enough to rebuild. ## Questions we are asked **What is software archaeology?** The disciplined investigation of an existing system to recover what it does, how it is structured, what it depends on and which of its behaviours carry business decisions, so it can be maintained, integrated or replaced on evidence rather than guesswork. **Do you need the source code?** Source is the best evidence, but an investigation can start from builds, binaries, databases, job schedules and operating documentation you are authorised to share. Every finding states the evidence it rests on. **Does an investigation mean the system has to be replaced?** No. The findings decide the path. Often the right outcome is to keep a working component and protect it properly, or to change one boundary rather than rewrite the whole application. **How is an engagement sized?** Around a question: what must be understood before this system can safely change, integrate, migrate or retire. The systems in scope, the evidence available and the timing are agreed before work starts. **What is legacy code?** Code that still works, that something important depends on, and that nobody can change with confidence. Age is incidental; the missing understanding is the problem, and an investigation recovers it. **Static or dynamic code analysis?** Both, plus the data. Static analysis recovers structure and dependencies from the source; dynamic analysis shows which paths actually run under representative inputs; data analysis finds the identifiers and relationships that give the code its meaning. ## Related work - [Legacy system modernisation](https://genyra.com/solutions/legacy-modernisation): Legacy modernization services: COBOL and mainframe application modernization to native software, not a conversion to the JVM estate that is now the next legacy. - [Systems integration](https://genyra.com/solutions/systems-integration): Systems integration services: contracts between systems, identifiers that mean the same thing everywhere, failure handling and a record of every handoff. - [Enterprise engineering](https://genyra.com/solutions/enterprise-engineering): Enterprise engineering for connected applications, architecture decisions, staged delivery and operational handover. Contact: contact@genyra.com Genyra LLC and the Dubai business Genyra L.L.C-FZ / Genyra.ai are distinct entities. Project scope and the contracting entity are agreed explicitly.