More › frontend

More

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>. state and env, 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/:id is UsersId). 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 an overlay: 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; back closes it. Name is the dialog component's, else its title's.
  • Events: onClick is on press, onChange is on change. A controlled input (value={x} and an onChange that sets x) is value x, which sets it. Actions are goto <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 no goto reaches. 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, switch reducers), 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 UsersId shows the screen, the code fills it.
  • A for draws 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 var for all its uses.
  • Running archec recover --ui again writes the model anew from the code: what was added in the model is not merged into it.