Account Profile & Company Entity Module Documentation

Module Code: billing/client/account-profile
Route: /portal/settings
Backend Service: clientService.ts (ring2all-billing-api)
Database Table: customers
Brand Purity: 100% White-Label Compliant (Ring2All Billing)

---

Table of Contents

1. Executive Summary & Corporate Identity
2. Technical Architecture & Profile Sync
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Screen Breakdown
5. Company Details, Tax ID & Invoicing Address
6. FormGrid Standardization & Action Bar Controls
7. Database Schema & Data Dictionary
8. Diagnostic CLI & Operational Playbooks
9. Domain Glossary

---

1. Executive Summary & Corporate Identity

The Account Profile & Company Entity module allows subscribers to manage their official corporate identity, authorized point-of-contact details, national tax registration numbers, and legal billing address used across all generated statements and PDF tax invoices.

+-------------------------------------------------------------------------------+
|                       COMMERCIAL & OPERATIONAL IMPACT                         |
+-------------------------------------------------------------------------------+
| • Automated Tax Accuracy: Changes to company address and tax identification   |
|   are dynamically reflected on subsequent PDF invoices and tax receipts.     |
| • Emergency Notice Dispatch: Direct maintenance, dunning warnings, and low-  |
|   balance alerts to the verified primary administrative email and phone.      |
| • Self-Service Governance: Eliminates support tickets for routine corporate   |
|   contact and office relocation updates.                                      |
| • Strict Form Standards: Complies with Ring2All Level 2 Form UI guidelines   |
|   with FormGrid alignment and lower FixedActionBar controls.                  |
+-------------------------------------------------------------------------------+

---

2. Technical Architecture & Profile Sync

When an administrator saves modifications in SettingsPage.tsx, the API validates the payload, updates PostgreSQL, and refreshes the client’s session context:

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Client Web Browser (Portal UI)                    │
 │                      Route: /portal/settings                           │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ PUT /api/client/profile
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │            Ring2All Billing API Engine (Fastify 5 / Zod Schema)        │
 │            • Validates International Phone E.164 & Postal Code Formats │
 │            • Sanitizes Tax ID & Legal Company Name                     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼ SQL UPDATE
 ┌────────────────────────────────────────────────────────────────────────┐
 │                    PostgreSQL 17 (public.customers)                    │
 │                    UPDATE customers SET company_name = ...,            │
 │                    tax_id = ..., billing_address = ..., city = ...     │
 │                    WHERE id = $authCustomerId                          │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ 200 OK + Refreshed Profile
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                  Client Session Context Hydration                      │
 │                  Updates React Context & Header Profile Display        │
 └────────────────────────────────────────────────────────────────────────┘

---

3. 🎯 User Roles & Key Capabilities

Management of corporate identity is restricted to primary tenant officers:

User Role	Access Level	Primary Operational Capabilities
Corporate Tenant Executive	Full Access	Updates corporate entity name, registers official tax ID, updates headquarters billing address.
Accounts Payable Supervisor	Contact Information	Verifies phone numbers, billing address lines, and accounts payable email recipients.
Compliance Officer	Audit Verification	Ensures legal tax identification matches national registries before high-volume trunk activation.

---

4. Visual Interface & Screen Breakdown

4.1 Account & Company Profile Settings

The profile form utilizes standardized FormBoxes and responsive FormGrids:

• ModuleFormHeader: Fixed 56px header displaying the building icon, module title (Account Profile), and navigation back button.
• Company Information Card: Fields for Primary Contact Name, Registered Company Name, Contact Phone, and National Tax ID.
• Billing Address Card: Fields for Street Address, City, State/Province, Postal Code, and Country dropdown selector.
• FixedActionBar: Bottom-anchored action bar featuring Cancel (resets form to original state without navigating) and Save Changes (submits payload).

---

5. Company Details, Tax ID & Invoicing Address

The profile configuration controls corporate tax calculations:

1. Tax Exemption Status: If a valid European VAT ID or US Resale Certificate number is filed and verified, the billing engine automatically applies zero-rated tax rules on invoice generation.
2. E911 Consistency: By default, new DID acquisitions can inherit the registered company billing address for emergency dispatch routing.

---

6. FormGrid Standardization & Action Bar Controls

In accordance with Ring2All UI Rule 8:

• Standard Grid Structure: All form elements utilize grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-x-6 gap-y-3 items-start.
• Label Baseline: Every <Label> enforces min-h-[40px] flex items-center to guarantee vertical baseline alignment across adjacent columns.
• Cancel Button Semantics: As per Rule 6, clicking Cancel restores the form to initial values without leaving the page.

---

7. Database Schema & Data Dictionary

Table: public.customers (Profile Subset)

-- Profile-specific columns in public.customers
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS name VARCHAR(255) NOT NULL;
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS company_name VARCHAR(255);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS phone VARCHAR(50);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS tax_id VARCHAR(50);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS billing_address TEXT;
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS city VARCHAR(100);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS state VARCHAR(100);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS postal_code VARCHAR(20);
ALTER TABLE public.customers ADD COLUMN IF NOT EXISTS country VARCHAR(2) DEFAULT 'US';

---

8. Diagnostic CLI & Operational Playbooks

Verify Customer Profile Record via Database

su - postgres -c "psql -d ss_billing -x -c \"
SELECT name, company_name, phone, tax_id, billing_address, city, state, postal_code, country
FROM customers
WHERE id = 5;
\""

---

9. Domain Glossary

• FixedActionBar: Bottom-docked UI toolbar housing primary persistence and form cancellation controls.
• Tax ID / EIN: Employer Identification Number or Value Added Tax (VAT) registry code.
• FormGrid: Standardized 4-column responsive grid layout ensuring field alignment.