---
title: "Account Profile & Company Entity Module Documentation"
description: "Documentation for Profile"
---

> **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](#1-executive-summary--corporate-identity)
2. [Technical Architecture & Profile Sync](#2-technical-architecture--profile-sync)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Screen Breakdown](#4-visual-interface--screen-breakdown)
5. [Company Details, Tax ID & Invoicing Address](#5-company-details-tax-id--invoicing-address)
6. [FormGrid Standardization & Action Bar Controls](#6-formgrid-standardization--action-bar-controls)
7. [Database Schema & Data Dictionary](#7-database-schema--data-dictionary)
8. [Diagnostic CLI & Operational Playbooks](#8-diagnostic-cli--operational-playbooks)
9. [Domain Glossary](#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:

![Account & Company Profile Settings](/screenshots/billing/client/account-profile/account-profile-form.png)

* **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)
```sql
-- 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
```bash
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.