For Systems Engineers · 30 minutes
Reading a portfolio.
A guide for engineers who arrive at a software portfolio the way they'd arrive at an unfamiliar circuit board: wanting to know what's there, what it does, what its limits are, and whether they can trust it. Written for readers with strong hardware/firmware/systems instincts and just enough software experience to be dangerous.
The new director.
Marcus has spent the last twenty years designing flight-control systems. RF, mixed-signal, embedded firmware, the occasional FPGA. He reads chip datasheets the way other people read the morning paper. Last Friday he started as Director of Engineering at a SaaS company — a step sideways from defense work into the world of microservices, Kubernetes, and continuous deployment.
He's responsible for fourteen teams. He doesn't yet know what most of them do. His Slack DMs are full of questions he can't answer because he doesn't know which service handles what. He needs a way to read this portfolio the way he'd read a board layout: rigorously, in his own time, without interrupting people.
Then his architect tells him: "We use Folio. Open the platform-portfolio repo. Everything we own has a datasheet."
Marcus has never used Folio before. He's about to discover that it speaks his language. For the rest of this guide, we'll watch him orient himself to a new portfolio using the skills he already has from twenty years of reading hardware documentation.
Survey the portfolio.
Marcus's first instinct is the same one he'd have walking into a new lab: show me everything that's here. In hardware, that's a parts inventory. In Folio, it's the same idea:
cd platform-portfolio folio list ID NAME LIFECYCLE MATURITY OWNER CLASSIFICATION ------------------------ ----------------------- --------------- --------- ----------------- -------------- auth-gateway Authentication Gateway active hardened identity-team internal billing-engine Billing Engine active stable finance-platform confidential customer-portal Customer Portal active stable web-team internal data-warehouse Data Warehouse active hardened data-team confidential dispatch-router Dispatch Router active beta routing-team internal event-bus Event Bus active hardened platform-team internal file-uploader File Uploader active stable web-team internal job-scheduler Job Scheduler active stable platform-team internal legacy-payments Legacy Payments deprecated hardened finance-platform confidential notification-svc Notification Service active stable platform-team internal report-generator Report Generator active beta data-team internal search-index Search Index active hardened data-team internal session-store Session Store active hardened identity-team internal sms-gateway SMS Gateway in-development alpha web-team internal 14 datasheets
Already, this is more than Marcus knew at 8:30 this morning. He counts: 12 active services, 1 in development, 1 deprecated. He notes the range of maturity: hardened (battle-tested), stable, beta, alpha. He sees five different teams. Two services are confidential.
This is exactly the table he'd hope to see if someone handed him a board with fourteen ICs on it. He doesn't know what each does yet, but he knows what he's working with.
folio list is the BOM. Each row is a part, each part has lifecycle status (think TI's "Active / NRND / Obsolete"), each has an owner who knows the part well.Get the shape of the portfolio.
Before reading any single datasheet in detail, Marcus wants to understand the distribution. How healthy is this portfolio overall? How much is mature? How much is being actively built?
folio stats folio stats 14 datasheets LIFECYCLE MATURITY active 12 alpha 1 in-development 1 beta 2 deprecated 1 stable 5 hardened 6 CLASSIFICATION OWNERS internal 12 data-team 3 confidential 2 finance-platform 2 identity-team 2 platform-team 3 routing-team 1 web-team 3 LAST REVIEWED fresh (<30d) 4 recent (<90d) 8 stale (<1y) 2 ancient (>1y) 0 REFERENCES links 36 interfaces 31 requirements 22
Marcus reads this the way he'd read a yield report. Six hardened components, five stable, three in earlier maturity stages. Four datasheets reviewed in the last month, eight in the last quarter, two stale (over 90 days). Nothing ancient. The portfolio is alive and being maintained.
The two stale datasheets stand out — he'll come back to those. But overall this is a well-kept portfolio, the kind you'd inherit from a careful predecessor.
Read a single datasheet end-to-end.
Now the part Marcus is best at: reading a single document carefully. He picks auth-gateway — the authentication layer is always a critical path, and "hardened" maturity tells him this is the production-grade piece.
folio show auth-gateway
Folio renders the datasheet to the terminal. Marcus reads it section by section, the way he'd read any new component's documentation. Here's what each section maps to in his hardware mental model:
Identity (the part number and packaging)
The first block tells Marcus what this is at the most basic level: identifier, owner, lifecycle, maturity, version, classification, last-reviewed date.
# Authentication Gateway
id: auth-gateway
owner: identity-team
classification: internal
lifecycle: active
maturity: hardened
version: 4.2.1
last reviewed: 12 days ago
Hardware analog: the first page of a chip datasheet, with part number, package, family, and current production status. Marcus knows this is a v4 component — it's been through three major revisions, which suggests real production usage. Hardened with a 12-day-old review means someone is actively maintaining it.
Snapshot (the abstract)
# Snapshot
Authentication Gateway is the front-door identity service for
all customer-facing endpoints. It handles SSO with the customer
identity provider, session management, MFA, and produces signed
tokens consumed downstream. Sustains 12,000 auth/sec across the
fleet at p95 latency under 80ms.
Hardware analog: the "general description" paragraph at the top of every datasheet. One paragraph, no jargon, tells Marcus exactly what role this plays. Useful before diving into specifics.
Interfaces (the pinout)
# Interfaces
## auth-api (REST over HTTPS)
The primary endpoint. Customer applications POST credentials and
receive signed JWT tokens. Fully documented in OpenAPI; spec lives
at /openapi.yaml on every running instance.
## auth-admin (gRPC over mTLS)
Internal endpoint for tenant configuration, identity provider
registration, and key rotation. Not exposed externally.
## /healthz, /metrics, /ready
Standard probes. /metrics emits Prometheus format.
Hardware analog: this is the pinout. Each interface is a pin (or pin group). What it's named, what protocol it speaks, what it's for. Marcus now knows there are three ways to talk to this service. He can plan accordingly.
Non-Functional (the electrical characteristics)
# Non-Functional
## Throughput
Sustains 12,000 authentications/second across the fleet. Per-pod
target: 800/sec. Verified by the load-test pipeline on every
release.
## Latency
auth-api p50: 22ms. p95: 78ms. p99: 145ms. Tail latency budget
is the primary release gate.
## Availability
99.99% target measured monthly. Achieved 99.997% over last four
quarters.
## Security
All sessions backed by HSM-stored keys. Token rotation 24h.
Audit log to immutable WORM storage.
Hardware analog: the recommended operating conditions plus the electrical characteristics tables. This is what the component is specified to do. Marcus reads this exactly the way he'd read VCC range, ICC quiescent, and propagation delay specs — as a contract about what behavior to expect within what envelope.
Dependencies (the application circuit)
# Dependencies
Required at runtime:
- session-store >= 2.0 (Redis-compatible, for live sessions)
- key-vault >= 1.4 (HSM access for token signing)
- postgres >= 15 (tenant configuration)
Required for build:
- protoc >= 3.20
Conflicts:
- legacy-auth (do not run both against the same tenant)
Hardware analog: the typical application circuit diagram, showing what other components need to be wired up for this part to work. Marcus now knows this service has hard runtime dependencies on three other components — he should look at their datasheets too if he's evaluating end-to-end behavior.
In ten minutes of reading, Marcus has formed a real opinion about this service. He could now have a credible conversation about it with anyone on the team.
Cross-reference: what depends on this?
In hardware, this is the question "where else is this chip used in this design?" In software, it's structurally identical: which other components in the portfolio require this one? Marcus runs:
folio query 'PREFIX folio: <https://folio.tools/vocab#> SELECT ?dependent WHERE { ?dependent folio:requires ?r . ?r folio:requirementName "auth-gateway" } ORDER BY ?dependent' dependent --------------------- ds:billing-engine ds:customer-portal ds:dispatch-router ds:file-uploader ds:notification-svc ds:report-generator 6 rows
Six components depend on the auth-gateway. That changes Marcus's mental picture: this is not just an authentication service, it's a load-bearing component — a single point of failure if it goes down, and a single point of leverage if anything changes about it. He'd want to be in the loop on any breaking changes to this service.
The query is an example of what makes Folio different from a wiki. Wiki pages can describe individual components. They cannot, by themselves, answer "which components depend on this one" without manual maintenance. Folio's structured fields make that question a one-line query.
Lifecycle awareness: the EOL parts.
Earlier, folio list showed one deprecated component: legacy-payments. In hardware terms, this is an "obsolete" part — technically still in production, but on a path to being removed. Marcus wants to know: is anyone still using it? What's the migration story?
folio show legacy-payments # Legacy Payments id: legacy-payments owner: finance-platform classification: confidential lifecycle: deprecated maturity: hardened version: 2.8.0 last reviewed: 47 days ago # Snapshot The original payments service. Replaced in 2023 by billing-engine for new customers. Kept online for the four enterprise tenants that have not yet migrated to billing-engine. Scheduled for full retirement once tenant-migration completes (target Q3).
Marcus reads this like a hardware end-of-life notice. A specific population of customers (four enterprise tenants) are still using the obsolete part. There's a documented migration path. There's a target retirement date.
To verify nothing inappropriate still depends on it:
folio query 'PREFIX folio: <https://folio.tools/vocab#> SELECT ?dependent WHERE { ?dependent folio:requires ?r . ?r folio:requirementName "legacy-payments" }' 0 rows
Nothing in the portfolio depends on legacy-payments — only direct customer traffic still hits it. That's the right state for a deprecated component on its way out. Marcus crosses it off his list of things to worry about.
The "confidential parts list."
Marcus's compliance officer is going to ask him within the week: which services handle confidential data, who owns each, when was each last reviewed? In hardware, this would be the ITAR or export-controlled parts list. In Folio:
folio query 'PREFIX folio: <https://folio.tools/vocab#> SELECT ?ds ?owner ?reviewed WHERE { ?ds folio:classification "confidential" ; folio:owner ?owner ; folio:lastReviewed ?reviewed } ORDER BY ?reviewed' ds owner reviewed -------------------- ----------------- ---------- ds:legacy-payments finance-platform 2026-03-08 ds:billing-engine finance-platform 2026-04-01 ds:data-warehouse data-team 2026-04-12 3 rows
Three confidential services. Two owners between them. Sorted by review date, oldest first — so the auditor's first question, "when was this last reviewed," already has its answer surfaced. Marcus saves the query as a script for monthly compliance reporting.
This kind of cross-cutting question is where the structured-data foundation pays for itself. A wiki cannot reliably answer it; a Folio repository answers it instantly.
Brief the CEO. Hand them a real datasheet.
Friday afternoon, Marcus has a meeting with the CEO and the head of sales. They're considering a deal that would require integrating with a customer's existing identity provider. The question on the table: can we credibly do this?
Marcus could verbalize the answer. Or he could do what he'd do in his old job: hand them a datasheet.
folio export auth-gateway ok: wrote out/auth-gateway-2026-04-24.pdf
One PDF. Typeset. Generated from the source the identity team maintains. It contains the same content Marcus has been reading all week, in a format that goes straight into the briefing packet without intermediation. The CEO doesn't need to ask "is this current?" because the document is dated and the lifecycle status is right at the top.
This is the workflow Marcus knew from defense work: when an integrator asks whether your subsystem meets their requirement, you don't write a memo. You hand them the datasheet and let them check it against their spec. Folio brings the same workflow to software.
The two stale datasheets.
Earlier, folio stats flagged two datasheets as "stale" (last reviewed 90+ days ago). A good systems engineer treats this the way they'd treat an out-of-date electrical specification: with skepticism. Marcus finds them:
folio query 'PREFIX folio: <https://folio.tools/vocab#> SELECT ?ds ?reviewed WHERE { ?ds folio:lastReviewed ?reviewed . FILTER (?reviewed < "2026-01-25") } ORDER BY ?reviewed' ds reviewed ---------------------- ---------- ds:dispatch-router 2025-12-18 ds:legacy-payments 2026-03-08 2 rows
One is the deprecated component (expected). The other is dispatch-router, which is in beta — an actively-developed component that hasn't had its datasheet reviewed in four months. That's a smell. Either the document has drifted from the implementation, or development has stalled. Either way, Marcus opens a Slack DM to the routing team to check in.
This is the daily working benefit. The portfolio's structural metadata makes it possible to spot, automatically, the small accumulating problems that would otherwise only surface during incidents.
The pattern, going forward.
Marcus now has a daily workflow that fits his instincts:
folio listin the morning. What's in the portfolio today?folio statswhen planning. What's the overall health?folio show <id>when evaluating any specific component.folio queryfor cross-cutting questions: dependencies, classifications, lifecycle.folio export <id>when handing a datasheet to a non-engineer.
Every operation is read-only against the local repository. Every result is grounded in the structured data the engineering teams maintain. Marcus doesn't need to know Python or Kubernetes manifests to be effective — the datasheet abstracts away the implementation, the same way a chip datasheet abstracts away the silicon.
This is the offer Folio makes to systems engineers, hardware engineers, and anyone else who has spent a career learning to read documentation rigorously: a software portfolio that can be read the same way. Same skill, new domain.
What just happened
Marcus knows the portfolio. He didn't write a line of it.
In one week, using only commands he learned in an afternoon, Marcus has formed a grounded technical understanding of fourteen production services. He can have credible conversations with any of the team leads. He can answer the CEO's questions with documentation rather than promises. He can spot stale documents and trigger their refresh.
None of this required reading code. None of it required interrupting an engineer mid-sprint. It required, instead, that the team maintain disciplined datasheets — the same kind of documentation they'd expect from any vendor whose component they integrate.
From here
Where to go next.
If you want to go deeper:
- Read the technical tutorial. If you want to understand how datasheets are created as well as how to read them, the main tutorial walks through the full author workflow.
- Browse the features. Every Folio command is documented at features, grouped by purpose.
- See more scenarios. The why page walks through five concrete situations where Folio changes the picture.