# Substrate: one repository for problems, solutions and the data behind them > Substrate is an open source framework, written in TypeScript and run with Bun, that holds problems, solutions, arguments, claims and outcomes in one place and links them to public data sources. It is aimed at people who want reusable, evidence-linked reasoning rather than another silo of notes. **danielmiessler/Substrate** — An Open-source Framework for Human Understanding, Meaning, and Progress. - Repository: https://github.com/danielmiessler/Substrate - Website: https://www.youtube.com/watch?v=ky7ejowc_qY - Stars: 931 · Forks: 128 - Language: TypeScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/danielmiessler-substrate ## What Substrate is trying to stop: the same problem solved twice Substrate is a repository of structured knowledge rather than a program with a command line interface. The framing it gives is that most people cannot build on solutions they cannot find, so it aims to be a single place where problems are documented with evidence, solutions are tracked with their results, and the reasoning in between is kept in the open. The vocabulary is the point. Instead of free-form notes, the framework defines object types, and the repository root is organised around them: Problems, Solutions, Arguments, Claims, Plans, Ideas, People, Organizations, Projects, Values, Models, Outcomes, Risks, Threats, Questions, Results, Frames, Experiments, Data and Funding-Sources. The project documentation describes this as more than seventeen object types. The audience is anyone who has hit the same wall twice and had no way to find the earlier attempt. The stated purposes are shared understanding, faster progress, evidence-based action, connected knowledge and collective intelligence, and the project is explicit that human contributors supply the framing while AI analysis contributes to the same objects. That mixture is unusual for a repository that otherwise looks like a well-organised archive, and it is the reason the framework treats arguments and claims as first-class records rather than footnotes. ## Problems and solutions are nodes, data sources are the other end The architecture is a graph, and the project publishes its own diagram of it. Human contributors and AI analysis both feed into the problem, solution and argument objects. Those objects in turn connect to data sources, arguments and claims connect to data sources, people connect to organizations, organizations connect to projects, and projects connect back to solutions. Problems, solutions, data sources and arguments all feed a shared understanding node. In concrete terms this means a solution is not a document, it is a record that points at the evidence that supports it and at the project that produced it. A claim points at the data source it rests on. That structure is what lets the same underlying dataset be reused across problems rather than downloaded again per project. On the data side the documentation speaks of thirteen data sources spanning more than a hundred years, drawing on government agencies and verified databases, with update frequencies ranging from real time to annual. The source evaluation follows library science methodology across eight dimensions, and each dataset is documented. The automation layer is TypeScript on the Bun runtime, and the project describes it as auto-discovery based. Two collector scripts sit at the root of the tree, `get-bay-area-covid-status` and `get-california-wastewater-data`, which suggests the data side is handled by per-source scripts rather than by a single unified ingestion service. ## A dataset list built around human wellbeing rather than GDP The most concrete part of the framework is the data catalogue, and the most recent expansion is documented in detail. An update in late October 2025 added eight sources measuring human wellbeing beyond traditional economic metrics, with five new US sources listed individually: FRED Economic Wellbeing for debt stress, unemployment and inequality, CDC WONDER Mortality for overdoses, suicides and deaths of despair, Census ACS Social for living alone, commute times and isolation, BLS JOLTS Labor for a worker permission-to-quit index, and EPA Air Quality for PM2.5, ozone and environmental health. The stated rationale is that measuring only GDP and unemployment misses slow-moving declines in human thriving. Each source is classified by what it captures: leading indicators such as financial stress that predict recessions, behavioural truth that acts reveal where surveys fall short, structural determinants such as air quality, crisis detection at county level, and worker agency expressed as a quit rate. Earlier updates in the same period refreshed Pulitzer Prize, GDP and inflation data, validated knowledge worker salary data, and added library science methodology, TypeScript automation with auto-discovery, central logging and health monitoring, and a documentation suite. Earlier still, the framework expanded its component types to include Plans, Ideas and Models, then added Claims, Arguments and Values frameworks along with TELOS integration, before the single repository structure with seventeen plus object types appeared in the foundation stage. ## Getting started without an install step There is no package to install and no binary to download, which makes the setup tutorial shorter than usual and worth spelling out plainly. The project states that the automation is TypeScript running on Bun, and that the repository is the interface: you clone it, read the entry points, and run the collectors and the framework against the data you care about. Two orientation documents sit in the repository root for exactly this purpose. GETTING_STARTED.md covers the first steps, and QUICK_REFERENCE.md is the condensed map of the object types and their fields. The documentation also points to a video introduction and a companion blog post on how the author's projects fit together, and a UPDATES.md changelog that carries the dated update history the project's overview lists. Because the project publishes no GitHub releases, there is no versioned artifact to pin. The last push was on 2026-10-22, and what changes over time is the content of the object directories and the collector scripts, not a packaged release train. If you want to know what the framework expects of you before writing anything, the two markdown files in the root are the shortest path. One caution for first-time users: the framework is MIT licensed and open, but the documentation does not describe a hosted service, so there is nothing to sign up for. You are working with a repository, which means every contribution is a file you commit. ## The gaps that decide whether Substrate works for you Several limitations are visible from the repository layout rather than from a changelog. The first is the absence of packaged releases. The repository has no GitHub releases, so there is no stable version to depend on and no upgrade path defined for downstream users. A fork that tracks main inherits whatever structure change lands next. The second is that the object model is the interface, and the object model is large. More than seventeen types with their own directories and their own fields means a contributor has to learn a vocabulary before making a useful contribution, and the relationships between Arguments, Claims and Results are where the real work happens. The third is the dependency on external data sources. Thirteen sources across more than a hundred years, with update frequencies from real time to annual, means the framework's value tracks the health of upstream publishers. The root-level collector scripts are the point where a change in an upstream schema breaks a run, and the documentation describes the collectors as auto-discovering rather than as a stable, versioned interface. The fourth is the AI dimension. The project's own diagram shows AI analysis writing into the same problem, solution and argument objects as human contributors. That is a deliberate design choice, and it means the framework mixes machine-generated content with human judgement in the same records without a documented provenance field separating them. ## Substrate beside a plain wiki and beside a plain database The nearest comparison is the wiki or notes folder most teams already have, and the difference is structural rather than cosmetic. A wiki holds prose and lets you link between pages. Substrate defines typed records, where a claim points at a data source and a solution points at a project, so a query can traverse the links rather than a reader following them. The other comparison is a database of datasets. A dataset catalogue tells you what data exists and how to download it. Substrate keeps data as one component among many, attached to problems and solutions, so the entry is not the data but the problem being addressed. The trade-off is obvious: the catalogue route gives you clean schemas and reliable queries, while Substrate gives you context and reuse across projects. A third option is doing nothing structured and relying on search. That works while one person holds the context in their head. It stops working when a second person needs to find the same prior attempt, which is the failure the framework is built around. What none of the alternatives give is the linking layer. If your need is a spreadsheet of indicators, a public statistics API, or a repository of markdown notes, those are simpler and will not rot in the same way, because they carry far less structure to maintain. ## MIT licensed, no releases, and a content-shaped maintenance burden The licence is MIT, which is the most permissive case for adoption. It allows use, modification, distribution and commercial reuse without any copyleft obligation, which matters if a company wants to run the framework on internal problems and solutions. The licence governs the code and the structure; the data sources carry their own terms, which are the project's own territory and not legal advice. Maintenance looks different here than in a typical library. There is no package to upgrade, so the upgrade cost is content review: new object types get added, collectors change as upstream schemas change, and the dated entries in UPDATES.md record that history. The repository was last pushed on 2026-10-22 and is not archived. The work of running the framework is also the work of curating it. Every argument and claim in the tree represents someone's reasoning attached to evidence, and if nobody maintains those links, the graph becomes a directory of files with no relationships. The community contribution framework, the contribution guidelines and the pull request process are the mechanisms for that upkeep, and the changelog shows them being used from the early stages onward. For an evaluator, the practical question is whether the graph stays connected as it grows. A framework of linked objects is only worth more than a folder of documents while the links still point at things. ## Conclusion Substrate suits a team or a lone researcher who wants prior work, claims and datasets to travel together in one repository instead of scattered notes, and who is willing to write in the project's object vocabulary. It does not suit someone who needs a working query tool over a specific dataset, because the repository is a knowledge structure rather than a data service. Before adopting it, read GETTING_STARTED.md and QUICK_REFERENCE.md and check that the object types in the root directories, Problems, Solutions, Arguments and Claims, match the way your own work is organised, since the value of the framework depends on that mapping. ## FAQ ### What is Substrate used for? Substrate is a framework for storing and linking knowledge objects such as problems, solutions, arguments, claims, plans, outcomes and risks, so that prior work and the evidence behind it can be found and reused. The repository root is organised into a directory per object type. ### What language and runtime does Substrate use? The project is written in TypeScript and uses the Bun runtime for its automation and data collection. The documentation describes the automation as TypeScript with auto-discovery. ### Does Substrate have versioned releases or an install step? No. The repository has no GitHub releases, and there is no package to install. You work with the repository itself, using GETTING_STARTED.md and QUICK_REFERENCE.md as the entry points. ### Which data sources does Substrate track? The project describes thirteen data sources spanning more than a hundred years, including five US wellbeing sources added in October 2025: FRED Economic Wellbeing, CDC WONDER Mortality, Census ACS Social, BLS JOLTS Labor and EPA Air Quality. ### What licence does Substrate use? Substrate is licensed under the MIT License, with the licence file at the repository root. Individual data sources keep their own terms. ## Sources - [danielmiessler/Substrate on GitHub](https://github.com/danielmiessler/Substrate) - [Issues](https://github.com/danielmiessler/Substrate/issues) - [License: MIT](https://github.com/danielmiessler/Substrate/blob/main/LICENSE) - [Project website](https://www.youtube.com/watch?v=ky7ejowc_qY) - [README](https://github.com/danielmiessler/Substrate/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/danielmiessler-substrate