LINKUWANT COMMUNICATIONS SYSTEM
===============================

STATUS
------
This directory currently contains communications architecture documentation
and placeholder templates only.

NO PRODUCTION COMMUNICATION SYSTEM IS IMPLEMENTED BY THIS STRUCTURE.


PURPOSE
-------
The goal is to create one common linkUwant communications system capable of
supporting:

- Email
- SMS/Text
- User confirmations
- Administrator notifications
- Administrator responses
- Multiple administrator recipients
- Form-specific responses
- Common replacement fields
- Form-specific replacement fields
- Authenticated administrator action links
- Communication logging


ARCHITECTURE
------------

Templates
    Define WHAT the communication says.

Configuration
    Defines WHERE information comes from and WHO receives communications.

Generator
    Will eventually retrieve data, normalize replacement fields, select
    templates, assemble communications, send communications, and log results.

Actions
    Will eventually support links from administrator communications to
    protected linkUwant functions.

Logs
    Will eventually record communication activity and delivery results.


DIRECTORY STRUCTURE
-------------------

/communications/

    README.txt

    REPLACEMENT-FIELD-STANDARDS.txt

    /email/
        README.txt
        header.html
        footer.html

        /offer/
        /we-buy-domains/
        /we-buy-ideas/
        /jobs/
        /contact/
        /feedback/
        /inquiry/
        /abuse/

    /text/
        README.txt

        /offer/
        /we-buy-domains/
        /we-buy-ideas/
        /jobs/
        /contact/
        /feedback/
        /inquiry/
        /abuse/

    /actions/
        README.txt

    /config/
        README.txt

    /logs/
        README.txt


TEMPLATE STANDARD
-----------------

Communication templates contain CONTENT ONLY.

Templates may contain replacement fields such as:

[first_name]
[last_name]
[company_name]
[email]
[phone]
[address]
[city]
[state]
[domain_name]
[submission_id]
[date]
[time]
[date_time]

Individual forms may define additional replacement fields.

Examples:

[offer_amount]
[message]
[domain_id]
[user_id]


IMPORTANT
---------
Friendly replacement field names do NOT have to match actual MySQL column
names.

Example:

Database column:
    do_first_name

Template field:
    [first_name]

The future communications generator will be responsible for mapping database
columns to friendly replacement fields.


TEMPLATES MUST NOT CONTAIN
--------------------------

- PHP code
- SQL
- Database credentials
- Authentication logic
- Recipient lookup logic
- Action-token logic
- Sending logic


ADMINISTRATOR ACTION LINKS
--------------------------

Administrator templates may eventually contain fields such as:

[view_submission_url]
[view_offer_url]
[view_domain_history_url]
[edit_submission_url]
[mark_junk_url]
[respond_url]

ALL administrator action links require authenticated administrator login.

The existence of an action URL or token NEVER grants authorization.

See:

/communications/actions/README.txt


DATABASE
--------

This scaffolding DOES NOT create database tables.

Each form README documents the proposed table name and field prefix.

Actual database tables, columns, indexes, relationships, and SQL must be
designed and reviewed separately when that individual form is built.


EMAIL
-----

Email templates are stored under:

/communications/email/

Each form directory contains:

user.txt
    Communication sent to the person submitting the form.

admin.txt
    Communication sent to the configured administrator(s).

Additional response templates may be added later.


TEXT / SMS
----------

SMS/Text architecture is reserved under:

/communications/text/

SMS functionality is NOT currently implemented.

Placeholder templates exist so future text functionality can use the same
general communications architecture.


IMPORTANT DEVELOPMENT RULE
--------------------------

Database submission is the authoritative record.

A future communication failure must NOT cause a valid form submission to be
lost or duplicated.

Communication failures should eventually be logged and handled separately
from the original form submission.


BUILDING EACH SECTION
---------------------

When ready to develop a particular form:

1. Read that form's README.txt.
2. Review its proposed database table and prefix.
3. Design the database table.
4. Design the form.
5. Define server-side validation.
6. Define CSRF protection.
7. Define spam controls.
8. Define database saving.
9. Define common replacement-field mapping.
10. Define form-specific replacement fields.
11. Define user email.
12. Define administrator email.
13. Define administrator recipient(s).
14. Define response templates if required.
15. Define authenticated administrator actions if required.
16. Define logging.
17. Test standalone form.
18. Test Corporate Website include.
19. Test Geo-Network include.
20. Review before production deployment.


SECURITY
--------

No communication template should ever be treated as executable PHP.

All protected administrator information and actions must require authenticated
administrator login and appropriate authorization.

Destructive actions should require confirmation before execution.

Sensitive actions such as payments, credentials, ownership changes, or broad
account administration must never be authorized merely because somebody
possesses a communication link.


THIS DIRECTORY IS A BLUEPRINT
-----------------------------

The current files document the intended architecture.

Production functionality will be built section-by-section after review.