1 files changed, 51 insertions, 0 deletions
diff --git a/docs/developers/overview.md b/docs/developers/overview.md
new file mode 100644
index 000000000..ca2d27985
--- /dev/null
+++ b/docs/developers/overview.md
@@ -0,0 +1,51 @@
+---
+layout: page
+title: High-level overview
+---
+
+# High-level overview
+
+<p class="lead">
+    This page describes the process and entities that make up Alaveteli.
+    It's a high-level overview of how Alaveteli works to help you orientate yourself to the code.
+</p>
+
+_See also the [schema diagram](#schema-diagram) at the bottom of this page._
+
+The main entity is **InfoRequest**, which represents a request for information by a
+**User** to a **PublicBody**. A new InfoRequest results in an initial **OutgoingMessage**,
+which represents the initial email.
+
+Once an InfoRequest is made, its state is tracked using **InfoRequestEvents**. For
+example, a new InfoRequest has an initial state of `awaiting_response` and an
+associated InfoRequestEvent of type `initial_request`. An InfoRequest event can
+have an OutgoingMessage or an IncomingMessage or neither associated with it.
+
+Replies are received by the system by piping raw emails (represented by a **RawEmail**)
+from the MTA to a script at `scripts/mailin`. This parses the email, tries to identify the
+associated InfoRequest, and then generates an **IncomingMessage** which references
+both the RawEmail and the InfoRequest.
+
+Any User can make **Comments** on InfoRequests.
+
+All events (e.g., Comments, OutgoingMessages) are tracked in InfoRequestEvent.
+
+A **TrackThing** is a canned search that allows users to be alerted when events
+matching their criteria are found. (How this worked changed after we'd
+launched, so there's still some deprecated code there for things we've phased
+out.)
+
+The **MailServerLog** is a representation of the parsed MTA log files.
+MailServerLog entries are created by a cron job that runs
+`scripts/load-mail-server-logs`. This checks incoming emails and matches them
+to InfoRequests; then `script/check-recent-requests-send` checkes these logs to
+ensure they have an envelope-from header set (to combat spam).
+
+## Schema diagram
+
+<a name="schema-diagram" href="{{ site.baseurl }}images/railsmodels.png"><img src="{{ site.baseurl }}images/railsmodels.png"></a>
+
+This schema for the Rails models was generated from the code on 19 Dec 2012 using
+[Railroad](http://railroad.rubyforge.org/).
+
+The railroad command is: `railroad -M | dot -Tpng > railsmodels.png`