Skip to content
GitHub

Architecture and project structure

The fastest way to read this repository for the first time is to follow one request through it. This page uses the user list (System → Users in the admin, GET /api/v1/sys/users) as the example, lists the files it passes through in order, and ends with a “what to change, where to look” table. To write a new module from scratch, see Add a business module from scratch.

Browser · apps/web + packages/platform + packages/api
  1. Route filedeclares URL params and the guard; renders nothing
  2. Page registryroute → page component
  3. The page's api.tsbuilds the query string, sends the request
  4. Request clientattaches the token · decides success or failure

GET /api/v1/sys/users · Authorization: Bearer <token>

Server · apps/api/backend
  1. JWT middlewareresolves the current user
  2. Permission dependencychecks the permission code
  3. apireads params, calls the service
  4. servicebusiness rules · pagination
  5. crudadds the data scope automatically

SQL · data-scope condition already attached

Database
  1. PostgreSQL · SQL Server · MySQLpick one; same code
Arrows show the request direction. The highlighted hop: row-level data scope is added to the query by the crud base class, not written by hand in each method

One pnpm + turbo monorepo holding the back end, three clients and this docs site.

apps/
├─ api/ back end (FastAPI, Python, managed by uv); code lives in apps/api/backend/
├─ web/ web admin: route files + the page registry, not the pages themselves
├─ desktop/ Electron desktop template; loads the web build
├─ mobile/ Expo mobile template with a native UI
├─ worker/ just a dev script that starts Celery
└─ docs/ this docs site
packages/
├─ api/ back-end contract: request client, success/failure rules, generated schema.d.ts
├─ i18n/ locale files and the check script
├─ ui/ generic components, no business logic
└─ platform/ pages, sign-in and permissions, the shell (tabs, sidebar)

Dependencies between packages go one way and are declared in each package.json:

PackageWorkspace packages it depends on
apps/web@admin/platform · @admin/ui · @admin/i18n
packages/platform@admin/api · @admin/ui · @admin/i18n
apps/mobile@admin/api · @admin/i18n
packages/api · packages/i18n · packages/uinone

Reverse the direction (say ui importing platform) and pnpm arch:check fails; CI runs it too.

Which files does one request pass through?

Section titled “Which files does one request pass through?”

Ten hops: the first four in the browser, the other six on the server.

#FileWhat this hop does
1apps/web/src/routes/_auth/system/user.tsxThe route file. Declares the URL parameters (page, filters) with zod and attaches the requirePerm guard; component: () => null, so it renders no page itself
2apps/web/src/lib/page-registry.tsxThe page registry. The line "/_auth/system/user": UserPage maps the route to its page component, which the multi-tab TabOutlet mounts
3packages/platform/src/pages/user/api.tsusersQuery turns the parameters into a query string and sends GET /api/v1/sys/users. The page’s index.tsx calls it through useQuery
4packages/api/src/client.ts · envelope.tsThe request client. Adds Authorization: Bearer and Accept-Language; on a 401 it refreshes the token once and replays. resolveEnvelope decides success: a bad HTTP status, or HTTP 200 with an envelope code other than 200, both count as failure
5apps/api/backend/middleware/jwt_auth_middleware.pyJWT middleware. Decodes the token, fills request.user, and puts the current user into context (hop 9 needs it)
6apps/api/backend/app/admin/api/v1/sys/user.pyThe endpoint, get_users_paginated. Its dependencies declare three things: RequestPermission('sys:user:list') (which code is required), DependsRBAC (the check) and DependsPagination (paging parameters)
7apps/api/backend/common/security/rbac.pyrbac_verify checks the permission: superusers pass; everyone else needs the code among the menus their roles have ticked
8apps/api/backend/app/admin/service/user_service.pyget_list. Asks crud for a query, hands it to paging_data, then attaches each user’s roles
9apps/api/backend/app/admin/crud/crud_user.py · common/security/data_scope.pyCRUDUser extends DataScopedCRUD. The base class overrides select / select_model / count and appends the current user’s data-scope condition to every query — which is why a department manager only gets users in their own department and below, and the page total is filtered too
10apps/api/backend/common/response/response_schema.py · utils/serializers.pyThe response. Every endpoint wraps its result in a { code, msg, data } envelope; stringify_unsafe_ints turns IDs beyond JavaScript’s safe integer range into strings, so the front end always receives IDs as strings

Three things that are easy to miss:

  • Route files do not render pages. Multi-tab keeps every open page alive, so pages are mounted by TabOutlet from the registry and route files only handle URL parameters and guards. Page components must not read the router either; parameters arrive as props. See Multi-tab.
  • Data scope is not written by hand. Hop 9 is done by the base class. When you really need to bypass it (a background job that must read everything), use bypass_data_scope(). Configuring the rules is covered in Data permissions.
  • Success is not decided in the page. HTTP 200 does not mean success; the envelope code does. That check lives in packages/api, so pages only handle successful data and a thrown ApiError.

Built-in features live in apps/api/backend/app/admin/, one directory per layer, called in the order api → service → crud:

apps/api/backend/app/admin/
├─ api/v1/ endpoints: read parameters, declare permission codes, call the service
├─ service/ business rules, transactions
├─ crud/ queries (extending DataScopedCRUD)
├─ model/ SQLAlchemy models, one class per table
├─ schema/ request and response fields (Pydantic)
└─ tests/ this module's tests

Removable features are plugins under apps/api/backend/plugin/: the same five layers plus a plugin.toml and their own sql/ seeds. See Plugins.

Pages live under packages/platform/src/pages/, one directory each. The user page has these files:

FileContents
api.tsThe API functions, types and query keys this page uses
columns.tsxColumn definitions and row actions
form.tsxThe create / edit form (react-hook-form + zod)
index.tsxThe page itself: query bar, table and pagination, with filters written to the URL
table-features.tsWhich table features this table turns on

I want to change something — where do I look?

Section titled “I want to change something — where do I look?”
What to changeWhere
Form fields and validationform.tsx in the page directory
List columnscolumns.tsx in the page directory
FiltersThree places together: searchSchema in the route file, the query-bar fields in the page’s index.tsx, and the function in api.ts that builds the query string
Request / response fieldsapp/admin/schema/ on the back end (plugin/<name>/schema/ for plugins). Then run pnpm --filter @admin/api gen:api to regenerate packages/api/src/schema.d.ts; hand-written types in the page’s api.ts need updating too
Business rulesapp/admin/service/
How a query is writtenapp/admin/crud/
Table structureChange the model in app/admin/model/, then pnpm db:revision 'message' to generate a migration and pnpm db:upgrade to apply it. Migrations are in apps/api/backend/alembic/versions/
Menus and button permission codesSeeds are the init_snowflake_test_data.sql files under apps/api/backend/sql/, one per database; seeds only run at initialisation, so a database already in use also needs a data migration. The back end declares codes with RequestPermission('…'), the front end guards with requirePerm(…)
UI text and translationszh-CN.json and en-US.json in packages/i18n/src/locales/, then pnpm i18n:check. Back-end messages are separate, in apps/api/backend/locale/
Environment variablesapps/api/backend/.env.example and core/conf.py
Settings editable in the UIThe config plugin, apps/api/backend/plugin/config/; see Config and data dictionary
Scheduled jobsapps/api/backend/app/task/; see Scheduled jobs
A page visible in the sidebarFive places: the route file, the page registry, the page directory, a sys_menu record and the locale files. Step by step in Add a business module from scratch

Where should an AI start reading this repository?

Section titled “Where should an AI start reading this repository?”

Conventions for coding agents live in the repository, not on this site: CLAUDE.md at the root holds the cross-module rules, and an AGENTS.md in each module directory holds the pitfalls measured in that layer. Claude Code loads the relevant one automatically when it reads a file in that directory.

On the docs side, every page has a Markdown source (the “Copy Markdown” button under the title, or replace the trailing / of the URL with .md), and the site index is llms.txt.