Short answer
Most tools that explain a codebase start by asking for the codebase. That is a reasonable design, and it is the one thing a lot of software owners cannot agree to — not because they distrust the tool, but because handing repository access to a supplier is a decision with consequences that outlive the analysis.
1ADK is built the other way round. The reading happens where the code already is, by the coding agent you already use. What reaches 1ADK is a description of the system, produced under an instruction you can read first — and it becomes part of your project only when you say so.
#Two ways in
They differ in who carries the description across. They do not differ in what crosses, or in who decides what is kept.
Every project has a connection page, and it asks how you want to work. Claude Code and Codex are connected by pasting in a block of text — Codex needs one line run in your own shell as well. Working by hand is the third answer on the same list, not a footnote under the other two, and it stays on the list after a machine is connected: some people will not connect anything to a repository, and that position does not cost them the product.
| What differs | Connected | By hand |
|---|---|---|
| Setting it up | Paste a block of text into your agent, once. Codex also needs one line you run yourself. | Nothing to set up. |
| Starting an analysis | Whoever connected the machine presses Scan now, and it picks the job up. | Anyone with the code copies the instruction and runs it. |
| Getting the result back | The machine sends the description when it is finished. | The agent writes a file; you read it and upload it. |
| What 1ADK receives | The same description. Never source code. | The same description. Never source code. |
| What gets written into your project | Only what you approve. | Only what you approve. |
| Ending it | Revoke the key. It stops working on that machine's next call. | Nothing to end — there was never a connection. |
The choice is not permanent
A project that was analysed by hand can be connected later, and a connected project can be left connected and still receive a file somebody produced on a machine that is not connected. The two roads meet at the same place: a description waiting for your approval.
#Connecting the agent you already use
A block of text, pasted into Claude Code or Codex — and for Codex one line you run yourself. There is no 1ADK program to install.
-
Open the connection page and pick your agent
The page asks how you want to work and offers three answers side by side: Claude Code, Codex, or by hand. Choose one of the first two and 1ADK shows you a block of text.
No repository URL is asked for, there or when the project is created. There is no field for one.
-
Paste the block into the agent
Paste it into an agent that is already open in the folder holding the code — that is what decides which project gets connected. It is a set of instructions written for the agent, not a command for you to understand: it claims a one-time code that is valid for minutes, adds 1ADK to its own list of tools, checks that the result works, and tells you in plain English whether it did.
The block never contains the key itself — the key does not exist yet when the block is written. Codex needs one extra line, run by you, because it will only take a fixed key from an environment variable; that line lasts as long as the terminal you ran it in, and 1ADK gives you a second one to keep it working in every terminal.
-
Ask for a scan when you want one
The connection page shows what is connected and offers Scan now. 1ADK opens the job; the connected machine asks for it, reads the system where it already sits, and sends the description back.
A machine answers the person who connected it, so Scan now belongs to them; anyone else on the project starts a scan by hand, and it covers the same ground. 1ADK never calls that machine — every exchange starts on your side.
-
You approve what gets written
A description that arrives is validated and then waits. You see a summary — how many components, how many unknowns, what the agent said it could not establish — and decide whether it becomes part of the project's knowledge.
Connecting an agent does not make anything automatic. This step is the same on both roads.
What the connected machine holds
A key for that one project, which lets it open a scan on that project, read the instruction for a scan waiting on it, send one description back against that scan, and ask what happened to it. That is the closed list; none of it takes a host, a path or a command, so there is nothing to aim anywhere else, and it reaches nothing else you own. It is never written into your repository — the instruction says so explicitly, because a key committed to a repository is a key that has been shared with everybody who ever clones it.
Revoking it is one button, on the same page that shows the connection, and it takes effect on that machine's next call. A key never gains a permission it was not issued with, which is what makes revoking it mean something.
#Doing it by hand
Nothing is connected, nothing is configured, and the product works.
Manual mode exists because the objection behind it is legitimate. If your answer to “may a tool hold a key that reaches this repository’s machine?” is no, that answer should not cost you an analysis. The agent is asked to look for the same things and the result is the same. One rule differs, and it is the one this road is chosen for: the manual instruction forbids the agent to open a network connection at all, and tells it to stop at a file on disk.
-
Copy the instruction
The scan page shows a block of text. It is copied into a coding agent — Claude Code, Codex, or any agent that can read a local repository — by whoever already has the code checked out.
The instruction is read-only and static: it forbids changing anything, running the application, running migrations or tests, and opening any network connection.
-
Read the file, then upload it
The agent writes one JSON file in your repository root and stops. Nothing is sent anywhere. Somebody opens it, sees exactly what it says about their system, and uploads it to 1ADK if they are happy with it.
This is the one road where a person can read every byte before it leaves the machine. That is the whole reason it is offered.
-
You approve what gets written
1ADK validates the file and holds it, exactly as it holds a description that arrived over a connection. Nothing is written into a project store until a person on your side approves that specific file.
Who does this in practice
Owners who do not write code almost always ask their developer or their agency to run the instruction. That works, and it does not weaken anything: the instruction is read-only, the file is plain text, and the person who approves it does not have to be the person who ran it.
#What crosses the boundary
The most important sentence about 1ADK is a negative one, and it is worth being exact about it. It is the same sentence on both roads.
- Names — of services, modules, classes, databases, queues, endpoints.
- Relative paths —
app/Services/PaymentService.php, and line ranges. - Kinds and relationships — this reads from that; this is deployed inside that; this implements that.
- Descriptions — a sentence per thing, written for somebody who does not read code.
- Claims and their evidence — a statement about one component, and the file and lines it was derived from.
- Unknowns — questions the agent could not answer, and why they matter.
- Coverage — which parts of the repository were actually looked at, and which were not.
- Source code. No file contents. No snippets. Not one function body.
- Configuration values. Nothing out of
.envor any config file. - Secrets. No tokens, passwords, keys, connection strings or cookies.
- Data. No rows, no dumps, no SQL, no customer records.
- Access. No repository credentials, no SSH key, no cloud role, no VPN, no inbound connection of any kind.
- Absolute paths. Relative paths only — a home directory is a person's name.
The part most vendors leave out
A lot of tools in this space promise that nobody else ever sees your source. 1ADK does not make that promise, because here it would be false: the coding agent that does the reading reads your code, and if it is a cloud agent then that vendor sees it, under their terms. That is already true of every other thing you ask that agent to do on that repository — but it is a different claim from ours, and merging the two would be dishonest.
The exact claim is: 1ADK does not require access to your repository and does not require uploading source code to 1ADK. The security page takes this apart properly, including what the boundary does not protect you from.
#What the description contains
It is a single JSON file, written in your repository root on both roads — so it is on your own disk to read whether or not you connected an agent.
The point of showing this is not the schema. It is that the unit of knowledge in 1ADK is a claim with a citation attached. Every statement the product later makes about your system can be traced back to a file and a line range that a person on your side can open.
{
"entities": [
{ "key": "svc.payments", "type": "SERVICE", "name": "PaymentService",
"description": "Creates and changes payment operations.",
"repository_path": "app/Services/PaymentService.php" }
],
"evidence": [
{ "key": "ev.create", "kind": "CODE_REFERENCE",
"summary": "Where the payment is created.",
"locator": { "path": "app/Services/PaymentService.php", "lines": "40-88" },
"confidence": "HIGH" }
],
"claims": [
{ "about": "op.create", "predicate": "idempotency",
"value": "Repeating a request with the same reference returns the first payment.",
"perspective": "OBSERVED", "evidence": ["ev.create"] }
],
"unknowns": [
{ "question": "What happens to a payment the provider never confirms?",
"why_it_matters": "Money may be taken with nothing recorded against it.",
"priority": "HIGH", "about": "svc.payments" }
]
}A path and a line range. A sentence. A confidence level. A question that was left open on purpose. Nothing that could be pasted back into an editor and compiled.
Two sections deserve more attention than the rest, because they are what makes the result usable by somebody who did not run the scan.
Coverage records what was actually looked at. A scan that
skipped vendor/ says so. This is why 1ADK can distinguish between
"this component is gone" and "we did not look there this time" — a distinction
that turns out to matter enormously the second time you run it.
Unknowns are a required output, not a failure. The instruction says as much to the agent: an empty unknowns list after one pass over a real system is a guess, not a finding. Why an unknown is a result goes into what this buys you.
#What happens after it arrives
Identical whether a person uploaded it or a connected machine sent it. The server does not trust one more than the other.
-
Quarantine
The bytes land somewhere that is not a project store and is not readable by the rest of the product. Nothing has been parsed yet.
-
Validation
The file is checked against the package schema, size limits and the job it claims to belong to. Free text is checked for the shapes credentials usually take — a bearer token, an AWS key, a private key header — and a package carrying one is refused outright.
This is a second line, not the first. The instruction not to include secrets comes before it, and your approval comes after it.
-
Your decision
A validated description waits. You see what is in it — counts, coverage, the limitations the agent declared — and either approve it or throw it away. Approval is per description, and it is explicit.
-
The write
An approved description is queued for that project's writer. One writer per project, short transactions, and a lock that is verified as still held. If the write fails, the store is left exactly as it was.
Each project's knowledge lives in its own isolated store. Two projects do not share a database, and there is no query in the product that can read across them. The public website you are reading has no access to any of it: it is a separate application with no platform database credentials at all.
#What you get back
- Product System map A system map is a structured account of what a software system is made of and how the parts relate. What belongs in one, what makes it trustworthy, and how it differs from an architecture diagram. What is a software system map?
- Product Evidence Every statement 1ADK makes carries the file, line range or configuration it came from. What evidence is, what confidence means, and why a checkable claim beats a confident explanation. How do I check whether a claim about my system is actually true?
- Product Unknowns An unknown is a result, not a failure. Why "not found" is not the same as "not there", how an open question gets recorded and closed, and why a document with no gaps in it should worry you. How do you document what nobody knows about a system?
- Product Change history Comparing two analyses of the same system gives four different answers — arrived, changed, gone, and no longer confirmed. Why the fourth one is the reason to keep analysing. How do I track how my system's architecture changes over time?
The shortest way to judge it is to open one. The demonstration project is a full analysed system — invented, and labelled as such on every screen — rendered by the same pages a customer's own project uses. No account needed.
#Running it again
This is the part that decides whether the product is worth anything after the first week.
A map of a system that has changed is worse than no map, because somebody will act on it. So the second analysis is not a repeat of the first — it is a comparison. 1ADK matches what the new description says against what it already holds, and reports four different things:
- Arrived — a component the previous analysis did not describe.
- Changed — the same component, described differently.
- Gone — and only where coverage was complete enough to say so. If the second scan did not look at that directory, 1ADK will not claim the component was removed.
- No longer confirmed — a claim that was made before and is not supported by anything in the current picture. It is not deleted; it is marked as something that used to be believed.
That last category is the one that does not exist in a document. A written architecture page goes stale silently. A technical memory that keeps its history can tell you which parts of what it told you last quarter it would no longer stand behind.
What 1ADK will not promise about keeping it current
You can tell a connected project how often you intend to update it — daily, weekly, or only when you ask. What that setting does is give you a line to put in your own scheduler, and show you on the connection page when the updates you said you wanted have stopped arriving.
1ADK does not run that line, and it does not open a scan on a timer of its own. It cannot: the machine that does the reading is yours, and a scan nobody is there to answer expires having achieved nothing except a row in your history that means your laptop was shut.
#What this does not do
What this does not do
- It does not run your software. Nothing is executed, so runtime behaviour — what actually happens under load, what a specific user sees — is outside what a scan can establish.
- It is not a security scanner. It does not test for vulnerabilities, and it does not claim your system is safe.
- It does not read what is not in the repository. A dependency configured in a cloud console and mentioned nowhere in the code is exactly the kind of thing that ends up as an unknown.
- It is only as complete as the analysis it was given. An agent that skipped half the system produces a picture of half the system — which is why coverage is reported rather than assumed.
- It does not reach your machine. Connecting an agent gives that machine a key to call 1ADK; it gives 1ADK nothing to call back with, and 1ADK never opens a scan of its own — every scan starts on your side, whether a person pressed the button or a scheduler you installed ran the line.
- It does not write your documentation for you. It records what is there and what is not known; deciding what to do about that is still a person's job.
Questions people actually ask
No. 1ADK has no repository credentials, no SSH access and no inbound connection to any machine of yours. Every exchange runs the other way: the machine on your side calls 1ADK over HTTPS, whether it is a connected agent asking for its next scan or a person uploading a file.
Who carries the description across. Connected, the person who connected the machine presses Scan now and that machine answers it. By hand, somebody copies the instruction, runs it, and uploads the file the agent writes. What the agent is asked to look for is the same on both roads, and so is what crosses the boundary; one rule differs — by hand the agent may open no network connection at all and stops at a file on disk, connected it may talk to 1ADK and to nothing else. Either way nothing becomes part of your project until you approve it.
A key for that one project, which you can revoke from the connection page at any time. It lets that machine open a scan on that project, read the instruction for a scan waiting on it, send one description back against that scan, and ask what happened to it. That is the closed list, and none of it takes a host, a path or a command, so there is nothing to aim anywhere else. It reaches nothing else you own, it is never written into your repository, and revoking it takes effect on that machine's next call.
Anyone who can already read the code — you, an in-house developer, your agency, or the developer who is leaving. It is a read-only task and it does not need an administrator. Connecting is done once by whoever has the code checked out; approving what gets written does not have to be the same person.
It is not sent to 1ADK. It is read by whichever coding agent does the reading, on the machine that agent runs on, under that vendor's terms — the same terms that already apply every time that agent is used on this repository. If your code may not be read by a cloud agent, run a local one, or do not run this at all.
Three things stand in the way. The instruction forbids values, secrets and file contents. Nothing is written into your project until a person looks at what arrived and approves it. And the server refuses a package whose text carries the shapes credentials usually take. None of the three is a guarantee, which is why the description is readable and the approval is a deliberate act.
The agent side depends on the size of the system and the agent — minutes for a small service, longer for a large monolith. Once the description arrives, validation is immediate and the write is queued; the map is readable as soon as it lands.
No 1ADK program, on either road. Connecting is a block of text pasted into the agent you already use: it adds 1ADK to its own list of tools and tells you whether that worked. Codex needs one line run in your own shell on top of that, because it will only take its key from an environment variable. By hand there is nothing to configure at all — the instruction is text.
Not by 1ADK's doing. 1ADK never opens a scan on a timer of its own, and it never reaches your machine. A scan starts when somebody presses the button — or, if you put the line 1ADK wrote out into your own scheduler, when that line runs on your machine and starts one there. That schedule is yours to install, change or delete; 1ADK only writes the line, and shows you on the connection page when the updates you said you wanted stopped arriving.