Your BusinessThe Contractor Codex

Setting up your organization

Your organization is the top-level container for everything you do in The Contractor Codex — clients, projects, quotes, contracts, invoices, and settings. It's also the brand wrapper: every page, PDF, and email your clients see is stamped with the org's name, logo, and accent color.

Step 1: Sign up

Go to /sign-up and create an account with email + password (or Google OAuth). The first time you sign in, you'll land on /org-setup, the one-time onboarding wizard.

If you ever get logged out mid-setup, sign back in at /sign-in and you'll return to wherever you left off.

Step 2: Name your business

The Business name field is the user-facing name that appears in your portal's header, on every PDF (quote, contract, signed agreement, invoice), and in every notification email. Use the name you'd write on a business card — not your legal entity name unless they're the same.

Examples:

  • ✅ "Acme Plumbing"
  • ✅ "Jane Smith Consulting"
  • ❌ "Acme Plumbing & Heating Services LLC" (too long; the LLC suffix takes up header space)

You can change this anytime in Settings (under the Branding section).

Step 3: Upload a logo

A square PNG between 200x200 and 1024x1024 works best. The logo appears in:

  • The portal header (left side, next to the business name)
  • Every PDF (quote, contract, signed copy)
  • Email notifications
  • Browser tab favicon

Keep the background transparent if you can. The portal renders against both light and dark surfaces, so a transparent PNG avoids a white box around your mark.

Step 4: Pick an accent color

The accent color drives every button, link, badge, and active-state highlight throughout the portal. Pick the color from your brand identity — it doesn't need to match your logo exactly but should complement it.

Common picks:

  • A saturated brand color (e.g., #e7c98b, the platform default)
  • A muted version of your logo color if your logo is highly saturated

You'll see the accent applied immediately after saving. Change it as often as you want.

Step 5: Set your support email

The support email is two things at once:

  • The contact address shown on client-facing pages, PDF footers, and "Contact us" links.
  • The recipient address for every client-activity notification (quote accepted, contract signed, change requested, declined). If you set it, those emails go here instead of your login email.

Use a real, monitored inbox. Leave the field empty if you'd rather have client-activity notifications come to the email you signed in with.

The "From" address on outbound emails to your clients comes from your email-sending domain (Step 6), not from this field. Replies to those emails route to whatever inbox you've configured at your DNS host for the From address.

Step 6: (Optional) Connect a custom email domain

If you have your own domain (e.g., acmeplumbing.com), you can send portal emails from that domain instead of from the platform default. See Settings → Email Domain for the DNS records to add.

This is optional but strongly recommended for trust signaling — clients are far less likely to mark emails as spam when they come from your domain.

What happens after setup

The wizard saves your organization and creates two things automatically:

  1. A Stripe Connect account (if you haven't already connected one) — see Connecting Stripe.
  2. An admin user that's you — the first member of the org with full admin rights.

You'll be redirected to /admin, the admin dashboard, where you can start adding clients and sending quotes.

Step 7: Save your signature

Visit Settings → Signatures and save a signature (you can type your name, draw with mouse/finger, or both). After that, every quote and agreement you send is automatically pre-signed by you at compose time. The recipient opens an authorized document and their signature finalizes it; no separate countersign step.

You can change your saved signature any time. The next outgoing contract picks up the new one.

Multi-admin orgs

Each org can have multiple admins. Every admin sees the same clients, projects, and settings, with actions audit-logged per admin. Manage your admin team from Settings → Team at /admin/settings/team. See Team management below.

Changing org settings later

Everything from this wizard is editable later:

The wizard exists just to make first-run setup fast. Everything is reversible.

Billing entity details

When you fill out the org-setup wizard, you also tell the portal who you are as a business entity. This data is used by Stripe Tax (if enabled), by your subscription invoices for The Contractor Codex itself, and to populate KYC documents Stripe might request later.

The relevant fields, all in Settings → Billing Profile:

  • Legal name — the name on your articles of incorporation. May differ from your business name (e.g., "ABC Holdings LLC" dba "Acme Plumbing").
  • DBA — your doing-business-as name if different from legal.
  • Entity type — sole_prop, llc, s_corp, c_corp, partnership, nonprofit, government, or other.
  • EIN last 4 — last 4 digits of your federal tax ID (for sole prop, last 4 of SSN). The portal never stores the full number.
  • Address — your business mailing address. Used for tax calculation by Stripe Tax (if enabled), and printed on your subscription invoices.
  • Tax exemption status — none, exempt, or reverse (for international reverse-charge VAT). If exempt, attach proof.
  • Accounts payable contact — name, email, phone of your billing/AP contact. The platform routes any billing questions about your subscription here.

You can fill these in later — they're not required to send quotes or invoices to your clients. They become required only if you enable Stripe Tax or run into a billing question.

Timezone

In Settings → Display, set your org's timezone. This drives:

  • Display of timestamps throughout the admin portal.
  • When recurring invoices fire (the cron uses the org's timezone to pick the right local day-of-month).
  • Calendar event sync timing.

Overdue-invoice reminders are timed from each invoice's due date, not your timezone, so they are unaffected by this setting.

Default is America/Los_Angeles. Change to whatever city/region you operate in.

Team management — two different things

There are two "Team" concepts in The Contractor Codex. They live on different sides of the portal:

1. Client team (your customer's team)

Each Client (one of your customers) can have multiple CustomerMembers — different people from that company who all log in to their portal. For example, Acme Corp's CFO and AP manager might both need access to download invoices.

Clients manage their own team from /dashboard/settings/team in their portal:

  • Owner invites teammates by email (14-day signup link).
  • Owner can remove teammates.
  • Owner status is held by whoever was first invited; promoting/demoting is currently a support-assisted action.

You don't manage this for them — they self-service from their dashboard. Your involvement is limited to support assistance if the owner asks for a promotion change.

2. Org admin team (your team)

Each Organization (your business) can have multiple OrganizationMembers — admins who log in to manage your portal. Same idea as client team, different table.

Manage your admin team from Settings → Team at /admin/settings/team:

  • Invite an admin — only the org owner sees this form. Enter an email + optional first/last name and click Send invite. The invitee gets an email with a secure 14-day signup link.
  • Pending invites show up in the list with an "Invite pending" pill. Owners can resend the link or remove the slot.
  • Remove an admin — owners see a Remove button on every other admin's row. Click to revoke access; their historical actions stay logged.
  • MFA badge — admins with multi-factor authentication enabled show a green MFA pill so you can audit at a glance.

The founder of the org is automatically the owner. Subsequent invites default to admin role. Both roles see everything (no per-feature permissions yet); the distinction is that only owners can invite + remove other admins.

Constraints

  • At least one owner. You can't remove the last owner. To remove yourself if you're the only owner, promote another admin to owner first — currently a support-assisted action while we build the promotion UI.
  • Email already used as a client. If the email you're inviting is already a CustomerMember (a portal user on the client side) in any org, the invite is blocked. The auth resolver can't route the same Clerk user as both a customer and an admin.
  • Self-invite. Inviting your own email is blocked — you're already a member.

What's still on the roadmap

  • Promote / demote between roles (owner ↔ admin) — currently support-assisted.
  • Granular permissions (e.g., a bookkeeper who can see invoices but not modify Stripe) — every admin currently has full access.
  • Last-active timestamp on each row.
  • Per-admin invite-link reminder emails.

Let us know in support if any of these are blocking.

Auto-created Stripe Connect account

The wizard creates a Stripe Connect Express account automatically the first time you save your org info. This is so you don't have to think about Stripe before you're ready to send your first quote. See Connecting Stripe for the rest of the onboarding.

The Express account is owned by Stripe (they handle compliance + payouts), with the platform as the connected-account host. You sign in to Stripe's hosted dashboard with the email you used during onboarding.

If you'd rather connect your existing Stripe account instead, skip the Express path and go to Settings → Stripe after wizard completion to OAuth into your existing account.

What "ready to send a quote" looks like

Before you can send your first quote, the portal needs:

  • ✅ Business name set
  • ✅ Logo uploaded (optional but recommended)
  • ✅ Stripe Connect account onboarded (charges enabled)
  • ✅ At least one client added (or just type an email in the quote composer)

If any of these are missing, the /admin page shows a banner telling you what's left. Click through to the relevant settings page to finish.

Common pitfalls

"My logo looks tiny on PDFs" — Upload at 512x512 or larger. The portal scales down for different surfaces but can't scale up cleanly.

"My accent color makes buttons unreadable" — Pick a color with at least 4.5:1 contrast against white text. Tools like https://webaim.org/resources/contrastchecker/ can verify.

"I can't change my org slug" — The slug (used in URLs like /admin/clients/<customer-slug>) is generated from your business name. To change it, contact support — slugs aren't user-editable to avoid breaking saved URLs.

"I want to delete my org" — Contact support. Deleting an org wipes all client data, contracts, invoices, and Stripe Connect account. We do it manually to prevent accidents.