A frontend repository as a model
You have a web frontend already: a React or Next.js app. archec recover --ui
reads its code and writes its user interface as an arche-lang model: each route
a screen, each modal a dialog, each shared component an element, its state
as vars and its event handlers as actions. You then add screens and elements
in the model, where archec checks them, instead of in the code.
Nothing of the repository is installed, built or run. The code is read with the
TypeScript compiler's parser only, so a repository whose npm install fails is
still read.
A first run#
archec recover --ui ../shop-admin -o ui.arche
✓ ui.arche — archec check: no errors, 2 warning(s) (ui-unreachable, ui-fit: archec check ui.arche)
frameworks: react; 6 screen(s), 1 dialog(s), 1 element(s) (1 use(s) written out), 17 var(s), 5 endpoint(s), 1 handler fn(s)
drawn: 68 of 69 elements are ui words (99%), 1 custom
events: 18 of 19 said in the model (95%), 1 call a handler kept in the code
notes (5): what the model does not say, a // recovered: comment where it applies
<canvas> is no ui word: a custom element (its code stays in the repo) (src/pages/Settings.tsx:28)
…
The model is checked by archec check before the command says ✓. Then:
archec ui ui.arche # the screens, element by element
archec ui preview ui.arche # screens.html: each screen drawn
| Option | Does |
|---|---|
-o ui.arche |
where the model goes; .archec/frontend-map.json is written beside it. Without -o the model goes to stdout and the report to stderr. |
--framework react,next |
the readers to run (react, next, vue, nuxt, angular, svelte, sveltekit); by default those package.json names |
--json |
what the readers found (the routes, components, stores, endpoints, types, notes and coverage), not the model |
The repository is test/fixtures/frontend/react-vite in arche-lang's tests: a
Vite app with react-router, a login form, a list from an API, a dialog, a
Zustand store, RTK Query and Tailwind classes.
What is read#
| In the code | Is read as |
|---|---|
function components (declarations, arrows, memo, forwardRef), class components (render(), this.state) |
components: their props, state, handlers and what they render |
| JSX: HTML tags, components of MUI, Chakra, Ant Design, shadcn/ui and Radix, react-bootstrap, Mantine | ui words by one table (src/frontend/elements.ts): div a column, nav a row, button, input type="checkbox" a toggle, select, img, progress a bar, MUI's TextField an input, a Dialog or Modal a dialog |
Tailwind and Bootstrap classes, inline style, a library's direction/spacing |
the layout: flex a row, flex-col a column, grid grid-cols-3 a grid of 3, gap-4 16 px, p-2, items-center, flex-1 (grow); btn-primary, variant="destructive" the style |
cond && <X/>, c ? <A/> : <B/> |
visible |
list.map((x) => <X/>), also kept in a const |
a for |
children, <Outlet/>, <Routes> |
where a layout puts the page |
useState, useReducer, useRef, class state |
the component's state |
Redux Toolkit slices, Zustand stores, React Context, useSelector |
stores; a reducer or action that only sets its state becomes those sets |
fetch, axios, an API client's .get/.post, a service function of the repo, react-query, SWR, RTK Query |
endpoints, with the request and response types the TypeScript says |
onClick, onChange, a form's onSubmit, useEffect(…, []) |
events: press, change, the submit button's press, the screen's on enter |
react-router (JSX <Route>, object routes, createBrowserRouter), Next.js app/ and pages/, TanStack Router |
routes, with their layouts |
An event handler becomes actions when each of its statements is understood:
setX(…), this.setState, navigate('/x'), router.push, <Link to>, a
request, a store's action, or a dialog's flag. When one statement is not, the
whole handler stays in the code and the model calls it. Vue, Angular and Svelte
have readers of their own, which plug into the same registry
(src/frontend/read.ts).
The model it writes#
These conventions are what the generator and the comparison of the model with
the code read back. The header of src/frontend/write.ts says the same.
The project and the system. project <Name>, Name the PascalCase of
package.json's name. system <Name>App has prop recovered = "archec recover --ui <repo>", part frontend: Frontend, and with endpoints part backend: Backend
and two links.
Types. A TypeScript interface or object type is a struct. A TypeScript
enum is an enum. A union of string literals is a string, its values said
in a comment. number is float64; a state with no type written is int32
when its first value is whole. An untyped value is a string, and the comment says so.
Endpoints. Each endpoint has an id: its method, then the words of its URL
(GET_api_users). It becomes message <id> "<METHOD> <url>" with the
request's fields, and message <id>_reply with the response's fields. A
request or reply that is not a record is one field, body. The Frontend
sends the requests on out api and receives the replies on in replies. A
component Backend has the matching in api and out replies.
The frontend. component Frontend "<app>" holds the lists of state as part
vars, since a ui keeps no array. Each handler kept in the code is a fn
whose body is // recovered: <file>:<line>. Then comes its ui.
The ui. It says display 1280x800, input pointer, theme light. The
screen of / comes first, so it is the one the ui starts on.
var: each state that is not a list. A component's keeps its name, or becomes<Component>_<name>when two components (or a store) have that name. A store's is always<store>_<name>.stateandenv, words of the ui, get a_after them.element Name(params): a component of the repo that others use, its props the parameters. Its callbacks (on…props, function-typed props) are not parameters.- Written out instead: a component that renders its
children, or whose uses pass callbacks that do something. An element has no slot and no callback, so it is written at each use, and a comment says so. screen <Screen> "<path>": each route. Screen is the page component's name when it has one route, else the PascalCase of its path (/users/:idisUsersId). The layouts around it (a Next.js layout, the component around<Routes>) are written around the page in each screen. A nav bar is part of every screen, not anoverlay: an overlay is drawn over a screen, a nav bar beside it.on enter: the page's mount effects and the requests its data needs.dialog <Name> "<title>" when <flag>: a modal shown while a state flag holds. Setting the flag opens it; inside it,flag = false; backcloses it. Name is the dialog component's, else its title's.- Events:
onClickison press,onChangeison change. A controlled input (value={x}and anonChangethat sets x) isvalue x, which sets it. Actions aregoto <Screen>,back,x = …,send api <id>(…), or<fn>()for a handler kept in the code.
A screen of the fixture, as it is written:
component Frontend "shop-admin" {
out api: data sends POST_api_login
ui {
var email: string = ""
var password: string = ""
var remember: bool = false
screen Login "/login" {
label "Log in" { size large }
input email "Email" { value email }
input password "Password" { value password }
toggle remember_me "Remember me" { value remember }
button log_in "Log in" {
enabled not (email == "" or password == "")
style primary
on press { send api POST_api_login { email: email, password: password }; goto Home }
}
}
}
}
What it cannot say. A tag with no ui word is a custom element with a
placeholder for the preview, and a // recovered: comment. An expression the
action language cannot say is a comment where it was. That means a call, a
list's .length, ?: or ??. The binding is then left out, and a text keeps
the expression as {code}. Nothing is guessed silently. The notes are also
listed at the end of the model and in the report.
The map. .archec/frontend-map.json says where each thing of the model
comes from: Screen, Screen.id, element Name, var x, fn f, message GET_x, each with its file, line and column in the repo. repo is the repo's
folder from the model's.
The report#
| Line | Says |
|---|---|
| frameworks | the readers that ran, and what was written |
| drawn | how many elements are ui words, and how many are custom |
| events | how many events are said in the model, and how many call a handler kept in the code |
| notes | what the model does not say, each with its file and line |
The model may have warnings, never errors:
ui-unreachable: a screen nogotoreaches. In a browser, any screen is reached by its address.ui-fit: a screen taller than 800 pixels. A web page scrolls; the model's display does not.ui-a11y: a control with no text, as the code wrote it.ui-structure: a toggle whose value is not said (its expression was a note).
On two public repositories, read in November 2026:
| Repository | Screens | Ui words | Events said |
|---|---|---|---|
reduxjs/redux-essentials-example-app, tutorial-steps-ts (RTK, RTK Query, react-router 6) |
7 | 97% (60 of 62) | 4 of 7 |
| gothinkster/react-redux-realworld-example-app (React 16, classic Redux, superagent) | 8 | 96% (165 of 172) | 12 of 45 |
The second one keeps most events in the code: classic Redux's connect and
superagent's requests are not read.
Limits#
- React and Next.js only, in this reader. Preact and Solid are read where they
write the same JSX; Solid's
<Show>is read, its<For>is not. - Read without types: a name the repo imports from a package is not followed, and a type is what the code writes, not what TypeScript infers.
- Classic Redux (
connect,mapStateToProps,switchreducers), MobX, Recoil, Jotai and XState are not read: their state is not in the model. - A handler is modelled whole or not at all.
if, loops,try, and a request's reply handled in code (.then(setUsers)) keep it in the code; a reply is said in a note. - A route's parameter (
/users/:id) is not passed:goto UsersIdshows the screen, the code fills it. - A
fordraws at most 10 rows (max 10). - An effect that runs when its dependencies change is a note. So are JSX made by a function call, props passed by spreading, and keyboard and focus events.
- A component's own state is one
varfor all its uses. - Running
archec recover --uiagain writes the model anew from the code: what was added in the model is not merged into it.