upstream-twenty/packages/twenty-apps/internal/twenty-partners/AGENTS.md

# 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/<primitive>/` 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
    <domain>/                    # partner · application · opportunity · …  (large domains add a <feature>/ tier)
      <name>.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 (<name>.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
`<feature>/` level — `modules/<domain>/<feature>/<primitive>/` (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 `<domain>/<primitive>/` 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 (`<name>.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

`<name>.<primitive>.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: `<name>.test.ts` = unit (mocked
client, fast, no infra); `<name>.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/`.