# Architecture — twenty-partners Vertical-slice modules, one folder per domain. Adapted from `twentyhq/twenty-eng` (the largest Twenty SDK app), which migrated flat → modular as it grew. Repo-wide conventions (kebab-case files, named exports, no `any`, `types` over `interface`, short `//` comments) live in the root `CLAUDE.md` and still apply — this file only adds the partners-specific structure. > **Status:** migration complete — every domain lives under `src/modules/`. The only > top-level `src/` entries left are `constants/universal-identifiers.ts`, `scripts/`, > `roles/`, `skills/`, `workflows/`, `__tests__/`, and the two root config files. Add new > code to a domain module, never a flat top-level `src//` folder. ## Layout ``` src/ application-config.ts # app + application variables — unchanged default-role.ts # unchanged constants/universal-identifiers.ts # ⚠️ MUST NOT MOVE (see Invariants) scripts/ # ⚠️ MUST NOT MOVE — seed/purge/rls/slugify roles/ # app-wide RLS — stays at root (spans every object) skills/ # bundled Claude skills — unchanged workflows/ # bundled workflows — unchanged __tests__/helpers/ # shared test setup (client, fixtures, cleanup) modules/ shared/ # cross-cutting: secret-guard (http/), find-or-create, paginate, # utils, front-components, cross-domain nav folders / # partner · application · opportunity · … (large domains add a / tier) .logic-function.ts # thin SDK entrypoints — sit at the domain/feature root, NOT in a subfolder objects/ fields/ view-fields/ views/ navigation-menu-items/ page-layouts/ # declarations constants/ # value lists + declaration UUID maps (NOT types) services/ # business logic (testable) graphql/{queries,mutations}/ # the only place raw queries/mutations live connector/ # OUTBOUND third-party API per folder (.connector.ts · config · types) mappers/ utils/ types/ front-components/ ``` A domain is a self-contained slice: its declarations (`objects`, `fields`, `views`, …) **and** its logic (`logic-functions` → `services` → `graphql`/`connector`) live together. Adding a feature means adding a folder, not scattering files across ten flat piles. **Feature tier for large domains:** when a domain holds several distinct features, insert a `/` level — `modules////` (the twenty-eng standard, e.g. `modules/code-build/build-task/services/`). It keeps `graphql/` and `services/` from becoming flat piles. Partner uses `partner/{self-service,marketplace,application-intake, directory}/…`; opportunity uses `opportunity/{intake,matching}/…`. A small single-feature domain (application) may keep `//` directly. ## The dependency rule (the one that matters — never import upward) ``` logic-functions → services → { graphql, connector, mappers } → shared · utils · types ``` - **Entrypoints (`*.logic-function.ts`, at the domain/feature root)** — SDK entrypoint ONLY. Parse input, call one service, return. No business logic, no raw GraphQL, no external HTTP. >~40 lines means it's doing a service's job — extract it. - **`services/`** — all business logic. Testable, no SDK/transport coupling. Must **not** import a `logic-function`. - **`graphql/`** — the ONLY place raw queries/mutations live (named typed operations, not inline `client.query(...)`). - **`connector/`** — the ONLY place **outbound** third-party APIs are called; one folder per API (`.connector.ts` / `config.ts` / `types.ts`). **Inbound webhooks are NOT connectors** — a webhook the app *receives* is an ordinary `logic-functions/` entrypoint guarded by the shared secret-guard util. (Today the one real connector is Discord; TFT/client-brief/ partner-application are inbound.) - Never import **logic** sideways between domains — share via `modules/shared/`. (A relation field naturally referencing its target object's ID constant is a schema reference, not a logic dependency — that cross-module import is allowed.) ## Naming `..ts` — e.g. `submit-application.logic-function.ts`, `resolve-candidacy.service.ts`, `partner.object.ts`. Files are kebab-case (no PascalCase, even for React components: `profile-picture-upload.tsx`). Tests co-locate with their subject and split by kind: `.test.ts` = unit (mocked client, fast, no infra); `.integration-test.ts` = real workspace (needs a live server + global setup; excluded by tsconfig). The split is a selectable vitest **project** (`--project unit`), not a file-count mandate — one `vitest.config.ts` with two projects is preferred. Don't rename a mocked unit test to `.integration-test.ts`. Shared test setup lives in `src/__tests__/helpers/`. ## Invariants (moving code must not break these) - The set of `universalIdentifier` UUIDs must stay **byte-identical** across a move — the SDK tracks primitives by identifier, not path, so a pure `git mv` is safe but a changed/dropped UUID re-registers or orphans an object. - **Do not move** `src/constants/universal-identifiers.ts` — the env-toolkit rewrites it by path per bundle. - **Do not move** `src/scripts/*` — `package.json` invokes them by path. - **Keep importers of `src/constants/universal-identifiers.ts` pointing at the root file** — don't relocate its UUID exports into a module. - **Never split a relation across domains with a dangling ID import.** Paired relation fields export/import each other's field-ID constant; keep both sides of a relation in one domain, or hoist the shared ID into `shared/`. - One domain per commit when migrating (`git mv` only, imports fixed in the same commit). ## Application review playbook The Matching Admin Workspace playbook is a standalone page in `src/modules/partner/application-intake/` (front-component + page layout + nav item). It must stay in lockstep with real behaviour. When you change any of the following, update the playbook in the same change: - Website form fields that land on Partner - The Partner Applications view (filter, columns, sort) - `validationStage` values used as the review decision - Intake side effects the reviewer needs to know (Discord on create; welcome email on `VALIDATED`, linked from `WELCOME_EMAIL_WORKFLOW_URL`) - Marketplace ranking bonuses in `packages/twenty-website/src/partners-marketplace/completeness-score.ts` (case study, cover, introduction, service, picture, calendar, rate, category, ghost rule) Facts on the page come from the same constants the view and intake use. Do not leave stale steps. Do not keep a second copy on twenty.com or in a Note. ## Opportunity process playbooks How to process (Matching Admin) and How to apply (Partner Workspace) are standalone pages under `src/modules/opportunity/how-to-process/`. They must stay in lockstep with real operator behaviour. Update the matching page and its copy test in the same change when you change any of: - Intake (marketplace brief already Listed + Discord; Twenty Internal unlisted; `/twenty-lead-brief` writes Design Doc URL) - Listing (`Listed` flip → Discord; daily digest; Open Briefs membership) - Intro (`Intro Sent At` turns Listed off; Invited applications) - Win (set Partner → Won / Declined; Backup stays; unassign reopens Won to Applied; Deals stages New → Screening → Meeting → Proposal → Customer) - Apply (Open Briefs listed-only; pitch minimum; one pitch; state meaning) - Bundled skills (`twenty-lead-brief`, `twenty-partner-shortlist`, `twenty-partner-intro`): local run, expected output, GitHub URL of `SKILL.md` - Match via MCP: the operator can ask the agent to write CRM changes Pages stay operator language. Skill names, slash triggers, and GitHub URLs of those bundled skills are allowed on How to process. Open Briefs and My Applications links are required on How to apply. Do not open Apply from the standalone page — Apply is pinned on the brief record. ## Where does new code go? External API call → `connector/`. Raw query/mutation → `graphql/`. Any logic → `services/`. New SDK trigger/function → a thin `*.logic-function.ts` at the domain/feature root that calls a service. Shared across domains → `modules/shared/`.