diff --git a/docs/core/architecture.md b/docs/core/architecture.md
new file mode 100644
index 0000000000000000000000000000000000000000..9993d6edf53ff9c7abfdebb19228c696406a6270
--- /dev/null
+++ b/docs/core/architecture.md
@@ -0,0 +1,167 @@
+# The codebase
+
+This chapter provides a general overview of the codebase organisation.
+
+In order to explore the directories inside the CiviCRM repository it is
+generally quickest to to make a local clone of the CiviCRM from GitHub.
+
+!!! tip
+ The CiviCRM codebase is object oriented. If you aren't familiar with object
+ oriented programming, spend a little time reading some beginner tutorials on
+ the net.
+
+## Namespaces
+Classes in CiviCRM must be placed in one of two folders:
+
+***`CRM`*** (e.g.: `CRM_Core_Invoke`)
+classes use PEAR-style class-naming conventions that were common up until
+PHP 5.2. Class names include underscores and MUST NOT use the PHP
+"[namespace](http://php.net/namespace)"
+directive. Use `CRM` style when creating classes that plug into existing `CRM`
+subsystems such
+as payment processors (CRM_Core_Payment) and reports (CRM_Report).
+
+***`Civi`*** (e.g.: `\Civi\API\Kernel`)
+"Civi" classes use PHP 5.3 namespaces. They MUST use the
+"[namespace](http://php.net/namespace)" directive.
+Namespaces are designated with "\".
+
+!!! note
+ At time of writing (May 2014, before Civi 4.5), some classes may not load
+ properly if they are in `Civi` – for example, the payment system will only load
+ payment-processor classes in `CRM_Core_Payment`. If you encounter problems like
+ this, please submit an issue or patch.
+
+!!! tip
+ The `Civi` namespace uses composer's PSR-0 autoloader. This autoloader does not
+ support custom PHP overrides.
+ Use `Civi` when creating new object-oriented subsystems (like `\Civi\API`).
+
+## Business logic
+Most of the business logic of CiviCRM, is found in the CRM directory (`CIVICRM_ROOT/CRM`).
+This logic is the part of CiviCRM that
+defines what it does and how it behaves
+(e.g. that allows people to register on events)
+In this directory, you will find directories for core CiviCRM functions like
+contacts, groups, profiles, deduping, importing, and the CiviCRM components
+like CiviCampaign, CiviMail, Pledges, etc.
+
+Each of these directories is slightly different depending on what they do but
+there are some common subdirectories: BAO, DAO, Form and Page.
+
+### DAO
+DAO stands for data access object. Code in this directory exposes the contents
+of the database. The DAOs are automatically generated for each release based
+on the data schema. DAO objects tend to be instantiated in BAO classes.
+
+The DAO has a property for each field (using the actual field name, not the
+unique name). They also have standard CRUD (create retrieve update delete) type
+functions, etc. <!--fixme why the etc? what else?? -->
+
+### BAO
+BAO stands for business access object. BAOs map to DAOs and extend them with
+the business logic of CiviCRM. A lot of the meat of CiviCRM is found in the
+BAOs, for example they have the code that creates follow up activities when an
+activity is created, or create activities and populating custom fields when a
+pledge is created.
+
+### Form
+In general each form page in CiviCRM maps to a file in one of
+the form directories. Form files contain a class that extends CRM_Core_Form.
+This class has different methods that the core calls before display to
+check permissions, retrieve information (`preProcess`), display
+the form (`buildForm`), validate the form (`formRule`) and carry out tasks once the
+form is submitted (`postProcess`). Forms can diplay information from the BAO
+to users and then call the BAO on submission. Generaly each form has an
+associated template (see below) which defines the form's html.
+
+!!! tip
+ Perhaps the best way to get to grips with the Forms is by experience and
+ experimentation.
+
+### Page
+If a CiviCRM screen is not a Form, it is probably a page. Pages files contain a
+class that extend CRM_Core_Page. Similar to the form class, Pages have methods
+that are called before the page is displayed to control access, set the title,
+etc. (`preProcess`), and when the page is displayed (`run`). Pages tend to
+take information from the BAO to be displayed to users. In general, each
+page has an associated template (see below) which is used to create the
+html of the page.
+
+### xml
+This directory contains a menu directory which maps urls to CRM form or page
+classes and controls access to these URLs using permissions.
+
+## Templates
+The templates directory contains all the HTML for pages and forms. Directly
+inside the templates directory is a CRM directory. In general, all templates
+map to a form or page class. CiviCRM chooses a template for the form or page
+based on the class name.
+
+For example, the class CRM_Member_Form_MembershipRenewal looks for a template
+in `templates/CRM/Member/Form/MembershipRenewal.tpl`.
+
+Templates are written in smarty, a common PHP template engine. Variables can
+be passed to smarty using the assign() method which is available to all Form
+and Page classes.
+
+Customising templates is discussed in more detail in 'Techniques'
+
+## The API
+The application programming interface (API) is stored in the api root
+directory. Best practice for using the API is discussed in more detail in
+'Techniques'
+
+## bin scripts
+The bin directory contains a variety of scripts that can be run to carry out
+specific functions. Some of these scripts are run on a regular basis, for
+example the CiviMail 'send' and 'process' scripts. Others are run on a one of
+or occasional basis, e.g. update geo-coding.
+
+## SQL
+The SQL directory is automatically generated as part of a release. It contains
+useful files like the SQL to create the database and insert demo data. Most
+developers won't need to edit files in this directory.
+
+## l10n
+This directory contains lots of automatically generated localisation files.
+You should not need to edit this directory directly. You should instead use
+CiviCRM's online translation tool transifex.
+
+## packages
+CiviCRM makes use of a lot of 3rd party packages for things like the database,
+ form, javascript and pdf libraries, wysiwyg editors and so on. You
+ shouldn't need to edit these packages directory.
+
+## Database structure
+The database structure is defined in a series of XML files. These files are
+not packaged in the releases but are available in the Github repository. They
+are located in Civicrm/xml/Schema. All the folders within this directory also
+have folders in the main CRM folder which contain a DAO folder and generally a
+BAO folder too.
+
+Looking in `CiviCRM/xml/Schema/Pledge` we see 4 files:
+
+- files.xml
+- Pledge.xml
+- PledgePayment.xml
+- PledgeBlock.xml
+
+The files.xml is just a list of the other files. Each of the others represents a
+table in the Database. The XML files describe the database and are used to
+build both the DAO files and the new database SQL generation script.
+
+The XML describes fields, foreign keys and indexes, an example of a field definition is:
+
+```
+ <field>
+ <name>amount</name>
+ <uniqueName>pledge_amount</uniqueName>
+ <title>Total Pledged</title>
+ <type>decimal</type>
+ <required>true</required>
+ <import>true</import>
+ <comment>Total pledged amount.</comment>
+ <add>2.1</add>
+ </field>
+```
diff --git a/docs/core/hacking.md b/docs/core/hacking.md
new file mode 100644
index 0000000000000000000000000000000000000000..3335f7945c1d6f9b8cd8ef7401d2ed21e969c995
--- /dev/null
+++ b/docs/core/hacking.md
@@ -0,0 +1,19 @@
+## When should I edit core CiviCRM?
+
+!!! danger
+ Most of the time, editing the core codebase directly
+ is not the recommended way for developers to customise and extend CiviCRM.
+ CiviCRM has two version releases per year so direct edits to the core codebase
+ will create upgrade issues for you.
+ There are other recommended ways for the majority of scenarios:
+ extensions, the APIs and hooks.
+
+To help you decide, here are a couple of principles:
+
+- Bug fixes should always be applied to core. Information on how to submit your
+ bug fix will be added soon. <!--fixme!! -->
+- Some (but not all) enhancements to existing features may be best applied to
+ core, especially if they would be useful to others.
+- New features should generally be packed as Extensions.
+- If you aren't familiar with CiviCRM, by far the best way to get a sense if
+ you should be editing core is by talking with the CiviCRM developer community.
diff --git a/docs/index.md b/docs/index.md
index dd90c6b0bbfa3ecba9facc26498c9ac0888c1a8c..2482a8b1ab3990eada914d00735ef2a3edbbfe41 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,5 +1,15 @@
# CiviCRM Developer Guide
+!!! warning "Notice"
+ This guide is not yet complete.
+ As of early 2017 we are actively working to migrate content in from the
+ [wiki]. Read more about this [migration process][migration], including how
+ to help out!
+
+[wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
+[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
+
+
[CiviCRM](https://civicrm.org) is an open-source application. The code can be
poked, prodded, twisted, and hacked. It can be customized, extended, and
collaboratively developed. This documentation tells you how to do that.
@@ -23,12 +33,4 @@ for use by people that are familiar with CiviCRM development.
for specific details on editing this documentation (and others using
mkdocs). You can also learn how to read these docs off-line!
-## Migration of content is in progress
-
-As of early 2017 we are actively working to migrate content from the [wiki] to
-this guide. Read more about this [migration process][migration], including how
-to help out!
-
-[wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
-[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
diff --git a/mkdocs.yml b/mkdocs.yml
index b0df87510338cc2c136b365574e921516b98594c..69654bf278005dd130aad371013d8372bc43060a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,9 +44,12 @@ pages:
# - Custom Reports: extensions/custom-reports.md
# - Custom Searches: extensions/custom-searches.md
# - Payment Processors: extensions/payment-processor.md
+- Core code:
+ - Hacking the core: core/hacking.md
+ - Architecture: core/architecture.md
- Miscellaneous:
- Extension Lifecycle: extend-stages.md
- Markdown: markdownrules.md
- - hookref-old: hookref-old.md
+ # - hookref-old: hookref-old.md
- Deprecated:
- Building CiviCRM from source: develop-deprecated.md
diff --git a/redirects/wiki-crmdoc.txt b/redirects/wiki-crmdoc.txt
index ca4c342bc709773af31dbd46922549ccce8aa758..963e632b274aec5b3408743e04de2146fc51b851 100644
--- a/redirects/wiki-crmdoc.txt
+++ b/redirects/wiki-crmdoc.txt
@@ -2,4 +2,6 @@ Documentation+Infrastructure+Canary develop
The+developer+community basics/community
Create+an+Extension extensions/basics
Before+you+start basics/planning
-Recommendations basics/planning
\ No newline at end of file
+Recommendations basics/planning
+The+codebase core/architecture.md
+