Appearance
SPEC-015: Company profile
APPROVED 2026-10-09 by the Product Owner, as part of the launch track "company-owned configuration" (ADR 0039). Amended 2026-10-13 by the Product Owner: the profile is suggested from Xero and Companies House for the owner to confirm (P11, P12), so the owner answers only what neither holds. Amended 2026-10-30 by SPEC-020 (issue #307): the profile gains
vat_registration_status(not_registered, registering, registered, or not known) andvat_registration_date(the effective date of registration).
Business intent
The deadline radar (SPEC-004), the VAT prompts and the confirmation statement check read each company's number, VAT quarters and payroll from a list in the code that names FEAW and WealthTechPros. A third company cannot use them, and the product cannot be sold while the code names its first two users. Each company's profile moves to the database, one row per company under row-level security, and the owner sets their own.
User story
When I start using GetMy Books for my company, I want to tell it my company number, when my VAT quarters end, whether I run payroll and my year end, so the deadline radar and the VAT steps work for my company.
Scope
- A table
entity_profile, one row per company (entity_idis the key): company number (8 letters or digits, as Companies House writes it), VAT quarter-end months (one of the three UK stagger groups: Jan/Apr/Jul/Oct, Feb/May/Aug/Nov, Mar/Jun/Sep/Dec; none when not VAT-registered or not known), whether the company runs payroll and whether it pays PAYE monthly or quarterly, and the year end (day and month; optional, Companies House's accounting reference date is used first). Row-level security like every other company table: a row is read and written only in that company's session, by a person with access to it. Rows are never deleted by the app role; deleting the account deletes a company only its owner used, profile included (SPEC-017 S11, throughdelete_company_for_principal). - Migration 0015 adds the table (expand only) and gives FEAW and WealthTechPros the profiles the code held, by entity name, once, never overwriting a profile already there and never when two companies share the name.
company_profile_set(MCP tool): the owner sets their company's profile. It writes to GetMy Books' own database only, never to Xero, so there is no approval card; the company comes from the session (rule 4).- The deadline radar, the confirmation statement check,
connection_check, the receipts checks that name another company, the VAT correction preview and the owner prompts read the profile from the database instead of the code. A company the owner can see with no profile is listed in the radar's notes, pointing tocompany_profile_set, and named in the radar'scompaniesWithoutProfileand at the top of its summary, so missing dates are never mistaken for no deadlines. - A new company needs its profile set: after connecting Xero on the web, the next steps say to set it with
company_profile_set(SPEC-017 S19), andconnection_checksays so for each company that has none. company_profile_setworks before the company is subscribed (SPEC-016 S23): it saves GetMy Books' own set-up only.
Out of scope
Reading the profile from Companies House or Xero automatically. Filing anything (rule 5, docs/not-doing.md). Deleting a profile on its own.
Data model sketch
entity_profile (entity_id uuid primary key references entity, company_number text not null, vat_quarter_end_months smallint[] null, runs_payroll boolean not null, paye_schedule text not null, year_end_day smallint null, year_end_month smallint null, updated_at). Checks keep the months to a stagger group, the PAYE schedule to monthly or quarterly, and the year end to a real day.
MCP tools sketch
| Tool | Does |
|---|---|
company_profile_suggest | Reads the company number, VAT registration and period, and year end from Xero, checks the number against Companies House, and replies with a suggested profile and what to ask the owner. Read-only; saves nothing |
company_profile_set | Saves one company's profile in GetMy Books (not Xero) and replies with what was saved |
Scenarios
gherkin
Feature: Company profile
Scenario: P1 the owner sets their company's profile
Given an owner with access to "Acme Ltd", which has no profile
When they call company_profile_set with company number "12345678", VAT quarters ending Mar, Jun, Sep and Dec, payroll monthly, and year end 31 March
Then the profile is saved for "Acme Ltd" in GetMy Books, not in Xero
And the reply shows what was saved
Scenario: P2 the company comes only from the session
Given an owner without access to "Other Ltd"
When they call company_profile_set with entity "Other Ltd"
Then it is refused and nothing is saved
Scenario: P3 a profile that is not a real one is refused
When the company number is not 8 letters or digits, or the VAT quarter months are not one UK stagger group, or the year end is not a real day
Then it is refused, saying which, and nothing is saved
Scenario: P4 the deadline radar reads each company's profile from the database
Given "Acme Ltd" has a profile with VAT quarters and monthly payroll
When the owner calls deadlines_upcoming
Then its VAT, PAYE and Companies House dates come from that profile
Scenario: P5 a company with no profile is named, not skipped silently
Given the owner can see a company with no profile
When they call deadlines_upcoming
Then its notes say the company has no profile and to set it with company_profile_set
And the summary starts by saying its dates are missing, and companiesWithoutProfile names it
Scenario: P6 the year end stands in when Companies House gives none
Given a profile with a year end, and Companies House gives no accounting reference date or cannot be read
When the owner calls deadlines_upcoming
Then Corporation Tax dates come from the profile's year end
Scenario: P7 one company's profile is never read in another's session
Given an owner with access to FEAW only
When a session for WealthTechPros reads or writes entity_profile
Then no row is returned and no row is written
Scenario: P8 the first two companies keep their profiles
Given entities named FEAW and WealthTechPros
When migration 0015 runs, and runs again
Then FEAW has company number 10345690, VAT quarters ending Feb, May, Aug and Nov, and monthly payroll, WealthTechPros has 14111544 and no VAT quarters or payroll, and a profile already saved is left as it is
Scenario: P9 connection_check says when a company has no profile
Given "Acme Ltd" is connected and has no profile
When the owner calls connection_check
Then Acme Ltd's row says it has no company profile and to set it up with company_profile_suggest, then company_profile_set (company number, VAT quarters, payroll, year end)
And a company with a profile has no such note
Scenario: P10 the profile can be set before subscribing
Given "Acme Ltd" has no live licence
When the owner calls company_profile_set for it
Then the profile is saved
Scenario: P11 the profile is suggested from Xero and Companies House
Given "Acme Ltd" is connected to a Xero organisation whose registration number is 12345678, with a VAT number, a quarterly VAT period and a year end of 31 March
And Companies House has company 12345678 named "ACME LIMITED" with an accounting reference date of 31 March
When the owner calls company_profile_suggest for "Acme Ltd"
Then it suggests company number 12345678, matching Companies House, the year end 31 March from Companies House, and VAT registered with quarterly returns
And it says to ask the owner which months the VAT quarters end in, and whether the company runs payroll, because Xero does not say
And it saves nothing
Scenario: P12 a number Xero does not hold, or Companies House does not match, is asked for
Given Xero holds no registration number for "Acme Ltd", or Companies House has none under it, or its name there is not Acme Ltd's
When the owner calls company_profile_suggest
Then it says so, and says to ask the owner for the Companies House number
And it never suggests a number Companies House does not confirm