<chapter id="archi">
  <title>Architecture &mdash; How Subversion's components work together</title>

  <simplesect>
    <para>Subversion is conceptually divided into a number of separable
      layers.</para>

    <para>Assuming that the programmatic interface of each layer is
      well-defined, it is easy to customize the different parts of the system.
      Contributors can write new client apps, new network protocols, new server
      processes, new server features, and new storage back-ends.</para>

    <para>The following diagram illustrates the "layered" architecture, and
      where each particular interface lies.</para>

    <programlisting><![CDATA[
                    +--------------------+
                    | commandline or GUI |
                    |    client app      |
         +----------+--------------------+----------+ <=== Client interface
         |              Client Library              |
         |                                          |
         |        +----+                            |
         |        |    |                            |
 +-------+--------+    +--------------+--+----------+ <=== Network interface
 | Working Copy   |    |    Remote    |  | Local    |
 | Management lib |    | Repos Access |  | Repos    |
 +----------------+    +--------------+  | Access   |
                       |     neon     |  |          |
                       +--------------+  |          |
                          ^              |          |
                         /               |          |
                   DAV  /                |          |
                       /                 |          |
                      v                  |          |
              +---------+                |          |
              |         |                |          |
              | Apache  |                |          |
              |         |                |          |
              +---------+                |          |
              | mod_DAV |                |          |
            +-------------+              |          |
            | mod_DAV_SVN |              |          |
 +----------+-------------+--------------+----------+ <=== Filesystem interface
 |                                                  |
 |               Subversion Filesystem              |
 |                                                  |
 +--------------------------------------------------+

]]></programlisting>
  </simplesect>

  <sect1 id="archi.client">
    <title>Client Layer</title>

    <para>The Subversion client, which may be either
      command-line or GUI, draws on three libraries.</para>

    <para>The working copy library, <filename>libsvn_wc</filename>, provides
      an API for managing the client's working copy of a project.  This
      includes operations like renaming or removal of files, patching files,
      extracting local diffs, and routines for maintaining administrative
      files in the <filename>.svn/</filename> directory.</para>

    <para>The repository_access library, <filename>libsvn_ra</filename>,
      provides an API for exchanging information with a Subversion
      repository.  This includes the ability to read files, write new
      revisions of files, and ask the repository to compare a working copy
      against its latest revision.  Note that there are two implementations
      of this interface: one designed to talk to a repository over a network,
      and one designed to work with a repository on local disk.  Any number
      of interface implementations can exist.</para>

    <para>The client library, <filename>libsvn_client</filename> provides
      general client functions such as <literal>update()</literal> and
      <literal>commit()</literal>, which may involve one or both of the other
      two client libraries.  <filename>libsvn_client</filename> should, in
      theory, provide an API that allows anyone to write a Subversion client
      application.</para>

    <para>For details, see <xref linkend="client"/>.</para>
  </sect1>

  <sect1 id="archi.network">
    <title>Network Layer</title>

    <para> The network layer's job is to move the repository API requests
      over a wire.</para>

    <para>On the client side, a network library
      (<filename>libneon</filename>) translates these requests into a set of
      HTTP WebDAV/DeltaV requests.  The information is sent over TCP/IP to an
      Apache server.  Apache is used for the following reasons:</para>

    <itemizedlist mark="bullet">
      <listitem><para>it is time-tested and extremely
          stable;</para></listitem>
      <listitem><para>it has built-in load-balancing;</para></listitem>
      <listitem><para>it has built-in proxy and firewall
          support;</para></listitem>
      <listitem><para>it has authentication and encryption
          features;</para></listitem>
      <listitem><para>it allows client-side caching;</para></listitem>
      <listitem><para>it has an extensible module system</para></listitem>
    </itemizedlist>

    <para>Our rationale is that any attempt to write a dedicated "Subversion
      server" (with a "Subversion protocol") would inevitably end up evolving
      towards Apache's already-existing feature set.  (However, Subversion's
      layered architecture certainly doesn't <emphasis>prevent</emphasis>
      anyone from writing a totally new network access
      implementation.)</para>

    <para>An Apache module (<filename>mod_dav_svn</filename>) translates the
      DAV requests into API calls against a particular repository.</para>

    <para>For details, see <xref linkend="protocol"/>.</para>
  </sect1>

  <sect1 id="archi.fs">
    <title>Filesystem Layer</title>

    <para>When the requests reach a particular repository, they are
      interpreted by the <firstterm>Subversion Filesystem
        library</firstterm>, <filename>libsvn_fs</filename>.  The Subversion
      Filesystem is a custom Unix-like filesystem, with a twist: writes are
      revisioned and atomic, and no data is ever deleted!  This filesystem is
      currently implemented on top of a normal filesystem, using Berkeley DB
      files.</para>

    <para>For a more detailed explanation: see <xref linkend="server"/>.</para>
  </sect1>
</chapter>
