# CRM Architecture and Delivery Plan

## Repository audit

The repository began as an unmodified Laravel 13.8 skeleton: one `User` model,
the default migrations, welcome route, Tailwind starter dependencies, and no CRM
domain code. There was no authentication UI, authorization model, localization,
business schema, design system, or meaningful test coverage. The supplied brief
mentions a reference CRM, but contains no URL or temporary credentials; therefore
no claim is made that reference workflows were inspected.

## Product architecture

The application is a modular Laravel monolith. HTTP controllers remain thin;
Form Requests validate input, policies enforce record access, Actions coordinate
business transactions, Eloquent models own relationships and casts, events/jobs
handle asynchronous side effects, and query objects serve dashboards and reports.
Blade, Bootstrap 5.3, logical CSS properties, and small ES modules form the UI.

Modules are grouped into Platform (identity, branches, teams, permissions,
settings, audit), CRM (leads, companies, contacts, activities, notes, tags,
files), Sales (pipelines, opportunities, products, quotations), Service (tickets
and SLA), Marketing (sources and campaigns), Performance (targets and
commissions), and Intelligence (dashboards, reports, imports, and exports).

Every business record is branch-scoped and supports ownership. Record visibility
is derived from role permissions plus `own`, `team`, `branch`, or `all` scope.
Writes use database transactions for multi-record workflows. Lead conversion,
quotation numbering, stage movement, imports, and commission calculation are
implemented as explicit Actions so they remain independently testable.

## Information architecture

1. Home: dashboard, personal agenda, notifications, global search.
2. CRM: leads, companies, contacts, customers, activities.
3. Sales: pipeline board, opportunities, products, quotations.
4. Marketing: sources and campaigns.
5. Service: tickets and SLA policies.
6. Performance: targets, commissions, reports.
7. Administration: users, branches, teams, roles, imports, audit log, settings.

Desktop uses a persistent navigation rail and compact top bar. Mobile uses an
off-canvas menu and preserves the same hierarchy. Arabic renders with `dir=rtl`,
an Arabic type stack, mirrored directional affordances, and logical spacing.

## Data model

Core tenancy and access tables: `branches`, `teams`, `team_user`, `roles`,
`permissions`, `permission_role`, and role assignments on users. CRM tables:
`leads`, `companies`, `contacts`, `activities`, `notes`, `tags`, `taggables`, and
`attachments`. Sales tables: `pipelines`, `pipeline_stages`, `opportunities`,
`products`, `quotations`, and `quotation_items`. Operations tables: `sources`,
`campaigns`, `tickets`, `sla_policies`, `targets`, `commissions`, `audit_logs`,
`imports`, `settings`, and `notifications`.

Money is stored as fixed-precision decimal with an ISO currency code. Emails and
phone numbers have normalized searchable columns. Human references are unique.
Foreign keys are indexed; deletion rules preserve financial and audit history.
Customer-facing and financial records use soft deletion. Dates are stored in UTC
and presented in the user's timezone.

## Permission matrix

| Role | Default visibility | CRM | Sales | Service | Reports | Administration |
|---|---|---|---|---|---|---|
| Super Admin | All | Manage | Manage | Manage | All | Manage |
| Administrator | All branches | Manage | Manage | Manage | All | Manage except system owner |
| Sales Manager | Branch/team | Manage | Manage | Read | Team/branch | Team users |
| Sales Agent | Own/team | Assigned records | Assigned records | Create/read own | Own | None |
| Support Manager | Branch/team | Read | Read | Manage | Service | Service settings |
| Support Agent | Own/team | Read | Read | Assigned tickets | Own | None |
| Marketing | Branch | Read leads | Read | None | Campaign | Sources/campaigns |
| Executive | All (read-only) | Read | Read | Read | All | None |

Permissions use `module.action` names (`leads.view`, `leads.create`,
`leads.update`, `leads.delete`, `reports.export`) and are always checked on the
server. Navigation visibility is only a convenience, never the security boundary.

## Security and quality baseline

CSRF protection, session rotation, hashed passwords, login throttling, escaped
Blade output, MIME/size-controlled private uploads, policy authorization,
allow-listed sorting, mass-assignment protection, audit redaction, and queue-safe
serialization are mandatory. Tests cover authentication, authorization, branch
isolation, CRUD validation, conversion, pipeline movement, quotation totals,
ticket SLA, localization, imports, and reports.

## Implementation roadmap

1. Foundation: identity, localization, navigation, permissions, branches, teams.
2. CRM core: leads, companies, contacts, activities, notes, files, tags.
3. Sales: pipelines, opportunities, conversion, catalog, quotations.
4. Operations: campaigns, tickets/SLA, targets, commissions.
5. Intelligence: automation, import/export, reports, audit, settings.
6. Hardening: performance, security, accessibility, mobile/browser QA, docs.

Each phase ends with fresh migrations, automated tests, logs inspection, English
and Arabic checks, permission checks, and responsive browser checks.
