------------------------
-- README for cdb.sql --
------------------------
v.1.7


Written by Patrick Walsh (patrick@phpgroupware.org)


Intro
-----
  This file is intended to explain the design ideas behind the cdb.sql
file.  That file defines a database structure for an Outlook-like
contact management system.  Hopefully the two will be completely 
compatible, but the cdb system will be far superior.


Database Tables and Relationships
---------------------------------
  This is a somewhat complex relational design with a number of 
many-to-one relationships.  However, this is the only reasonable way
to create a very usable and flexible contact database.  Some of the 
design goals are listed in the next section.

   - contact_main 
        Core information that would be displayed on the main page.  This
        includes names, profession, title, and links to the primary
        contact methods such as the mailing address, the top four phone
        numbers, main e-mail, main organization, etc.

   - contact_meta
        Stores meta info such as date created, date last modified, file_as,
        flag_status, followup_status, created_by, group_access
        permissions, etc.

   - contact_personal
        Stores info, where applicable, such as birthday, children, 
        hobbies, spouse name and so forth.

   - contact_client
        Contains a customer_id, billing_info, referred_by and account 
        info.

   - contact_notes
        Contains just the note associated with each contact, if one
        exists.  This is in it's own table to keep the other tables
        optimized.

   - contact_internet
        Contains a contact's internet info.

   ** Note that all of the above tables have a one-to-one relationship to
      each other.  There is an entry only if data of a given type is 
      entered.

   - contact_phone
        This table contains all phone numbers associated with all
        contacts.  Someone wanting to see all phone numbers for a given
        contact would effectively select all phone numbers in this table
        belonging to the selected contact.

        Each phone number has the number (up to 100 chars), a link to the
        phone_category and a link to the contact_id.

   - contact_phone_category
        This is a table that can be customized by the sysadmin and it 
        contains a comprehensive list of different types of phone 
        numbers.  Business Phone, Business Fax, Car Phone, Vacation Home
        Phone, Home Phone, etc., are all examples of phone categories.

        There can be any number of phone numbers in a given category for 
        a particular contact.

   - contact_address
        Contains the elements of an address, a link to the associated 
        contact, and a link to the address_category.  This works in the
        same way as contact_phone.

   - contact_address_category
        Works in exactly the same way as the contact_phone_category.

   - category
        Contains a list of all categories.  Simply contains the category
        id and associated category name.

   - category_link
        This is how each contact can be a part of multiple categories.  
        Each contact/category pair has a line in this table.

        Organizations can also be categorized.  This table now (v.1.1)
        has a flag for determining whether the link is to an organization
        or to an individual.

   - language
        Works very much like category: contains a list of languages and
        associated language codes.  These are the two digit language
        codes used by phpgw.

	Unlike categories, there is only one language per contact.  This
        is stored in the contact_personal table.  If there is no entry in
        that table for a given contact, English (en) is assumed.

        Perhaps language should be in contact_main instead?

   - contact_flag
        This table has a list specific to each user with what labels --
        called status flags by Outlook -- they want available for each
        contact.  

        This table stores the user_id the flag_name, the flag_color and
        the flag_id.  A flagged contact gets a background in of 
        flag_color.

   - contact_flag_link
        Each user gets one flag per contact.  This table has the user_id,
        the user's unique flag_id, and the contact_id.

   - contact_followup
        Systemwide list of followup flags such as "Send E-mail," "Send 
        Letter,"Call," "Arrange Meeting," or whatever suits a particular
        installation.  The table has a followup_id, followup_name and
        followup_color for the flag color.

        The contact_meta table has a reference to one of these.

   - organization
        This is where it starts getting complex and there are still a few
        design questions.  

        This table has a list of organizations with an id for each, a 
        name for each, the main phone number, the home page, etc.  
        
        Perhaps we should have tables for allowing multiple locations and
        different phone numbers for different office locations and then 
        allow each contact to associate themselves with a particular 
        office...?

   - organization_notes
        One to one relationship to organization.

   - organization_client
        One to one relationship to organization.  Functions exactly like
        contact_client except that it allows for organizations to be 
        customers/clients.

   - organization_meta
        Same as contact_meta but for organizations.

   - organization_location
        Each organization can have multiple office locations with 
        distinct addresses and phone numbers.  A contact is not just 
        associated with an organization, but with a particular location
        and organization combo.

   - contact_organization_link
        [this table has been removed.  the contact_organization table
        achieves the same purpose]

   - contact_organization
        This is perhaps the most complex table as it has a many to many
        relationship between contacts and organizations.  Each contact
        has a main organization selected in their contact_main table.

        This is a table with org_id <-> contact_id links.

        For any link where there is more specific information to be 
        added such as the contact's assistant's name/number at the 
        organization, the contact's manager's name/number, office
        location and so forth.
        

Design Goals
------------
  There are a number of situations where normal contact management 
databases fall short and a select few situations where Outlook falls 
short.

  Imagine the contact database of a Certified Public Accountant.  Such a
database would be filled with clients, attorneys, other cpa's, business
contacts, companies, trusts, personal contacts and so forth.  Many of 
these people could fall into multiple categories: an attorney and a 
client, for instance.  This brings me to the first design goal:

    1) Categorization of contacts where one contact may be in any number
       of categories.

  Most addressbooks allow for a person to have a home and work address
and home and work telephone numbers.  Unfortunately this can leave a
large number of phone numbers for the Notes section.  Consider the CPA's
rich clients who have multiple homes, perhaps multiple office locations,
a pager, a cell phone, a private line, a normal line, etc.  Don't laugh,
I have a good six telephone numbers myself and I have contacts who have
more than that!  This brings me to the second design goal:

    2) Allow for an unlimited number of phone numbers in which there are
       four primary numbers and any number of additional numbers.  Each
       number is associated with a phone category such as Business Phone,
       Business Pager, Business Fax, Home Phone, Home Fax, Vacation Home,
       and so forth -- and there can be any number of each of these.  The
       list of categories could be customized by the sysadmin.

       A similar system would be used for addresses with one marked as
       the primary mailing address for mail merge operations and such.

  Next, one often has a number of contacts in the same company.  For 
instance, suppose our CPA uses a law firm, but several different 
attorneys within the law firm for different areas of law.  Outlook and 
most other contact databases force you to put the company information in
for each person.  This is a waste of time and space and is a potential
source of typos that could mess up filters for a particular company.
Further, a company can be a contact with further contacts within the 
company.  This brings me to the third design goal:

    3) Create a system by which contacts can share company information.
       Company information includes the company name, main phone number,
       home page, notes, and id number.

       But lets not limit ourselves to companies -- let's call these
       organizations and let them be any legal entites: estates, trusts,
       companies and so forth.  In such cases the id number would be the
       federal id number used for taxes -- similar to an individual's
       social security number.  This is probably specific to CPA's.

       Any given contact can be associated with a number of 
       organizations.  A person may be the executor of an estate, work 
       for a company, and be a beneficiary of a trust.

  There is a need also for information that is specific to a particular
contact in conjunction with a particular organization.

    4) A contact may have an assistant's name, an assistant's phone 
       number, a department name, a manager's name and so forth for 
       each organization that a contact is associated with.

  There needs to be a framework for contacts who are also customers or
clients.  One would want to assign each of these people client or customer
id numbers for tracking billing histories, support histories, and so 
forth.  But such data would be tracked in another database system.

    5) Each contact who is a customer/client would have a customer id,
       billing info, who they were referred by, and an account.  Further,
       organizations may also be customers/clients and as such they can
       also have customer id numbers, billing info, etc.

  Contact entries can store personal information to jog the memories of
forgettful people like me.

    6) Optionally store personal info such as hobbies, childrens' names,
       spouse's name, anniversary, etc.

    7) File As field for determining where to file a company or person --
       for instance, if a married friend has adopted her husband's name, 
       but you can only remember her maiden name, you might have her last
       name properly listed, but still file her under her maiden name.

  There should be a mechanism for flagging and/or labelling contacts.  
There are times when it becomes obvious that a contact's information is
out of date and you want someone to review the information.  Or you may
want to flag a contact for later followup.

    8) Each person can make their own set of status flags and these flags
       will act like Eudora labels.  When flagged, the contact row will 
       be colored with the color of the flag. Each person could use this
       feature in their own way.  Sales people may want to label
       potential customers with different colors depending on their 
       chance of making a sale.

    9) There will be a system wide list of follow-up flags that can be 
       associated with a contact.  Such flags would be seen by anyone,
       in contrast to the user-specific labels above.  Example values
       that would add a colored flag to a column are:

              - Follow-up
              - For your information
              - Review
              - Call
              - Send E-mail
              - Send Letter
              - Arrange meeting

  Few contact management databases provide sufficient Internet
information.  There needs to be a framework for storing e-mail 
addresses including personal and work e-mail, ftp, personal
home page, business home page, icq number and so forth.

    10) Use a table to store internet contact info.

    11) Provide a mechanism for storing a contact's spoken language
        so that correspondence is done in the correct language.
