1 files changed, 60 insertions, 0 deletions
diff --git a/docs/api-concepts.rst b/docs/api-concepts.rst
new file mode 100644
index 0000000..075498b
--- /dev/null
+++ b/docs/api-concepts.rst
@@ -0,0 +1,60 @@
+Gerbonara API concepts
+======================
+
+High-level overview
+-------------------
+
+Gerbonara's API is split into three larger sub-areas:
+
+**File API**
+    This is where the main user interface classes live: :py:class:`.LayerStack` (for opening a directory/zip full of
+    files, and automatically matching file roles based on filenames), :py:class:`.GerberFile` (for opening an individual
+    RS-274X file), :py:class:`.ExcellonFile` (for Excellon drill files) and :py:class:`.Netlist` (for IPC-356 netlist
+    files).
+
+**Graphic Object API**
+    This is where the nuts and bolts inside a :py:class:`.GerberFile` or :py:class:`.ExcellonFile` such as
+    :py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc`, :py:class:`.Region` and :py:class:`.Flash`
+    live. Everything in here has explicit unit support. A part of the Graphic object API is the :doc:`Aperture
+    API<apertures>`.
+
+**Graphic Primitive API**
+    This is a rendering abstraction layer. Graphic objects can be converted into graphic primitives for rendering.
+    Graphic primitives are unit-less. Units are converted during :py:class:`.GraphicObject` to
+    :py:class:`.GraphicPrimitive` rendering.
+
+The hierarchy works like: A :py:class:`.LayerStack` contains either a :py:class:`.GerberFile`, an
+:py:class:`.ExcellonFile` or a :py:class:`.Netlist` for each layer. Each of these file objects contains a number of
+:py:class:`.GraphicObject` instances such as :py:class:`~.graphic_objects.Line` or :py:class:`.Flash`. These objects can
+easily be changed or deleted, and new ones can be created programmatically. For rendering, each of these objects as well
+as file objects can be rendered into :py:class:`.GraphicPrimitive` instances using
+:py:meth:`.GraphicObject.to_primitives`.
+
+Apertures
+---------
+
+Gerber apertures are represented by subclasses of :py:class:`.Aperture` such as :py:class:`.CircleAperture`. An instance
+of an aperture class is stored inside the :py:attr:`~.graphic_objects.Line.aperture` field of a
+:py:class:`.GraphicObject`. :py:class:`.GraphicObject` subclasses that have an aperture are
+:py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc` and :py:class:`.Flash`. You can create and
+duplicate :py:class:`.Aperture` objects as needed. They are automatically de-duplicated when a Gerber file is written.
+
+Gerbonara has full aperture macro support. Each aperture macro is represented by an :py:class:`.parse.ApertureMacro`
+instance. Like apertures, :py:class:`.parse.ApertureMacro` instances are de-duplicated when writing a file. An aperture
+macro-based aperture definition is represented by the :py:class:`.ApertureMacroInstance` subclass of
+:py:class:`.Aperture`. An aperture macro instance basically binds an aperture macro to a given set of macro parameters.
+Note that even if a macro does not accept any parameters you still cannot directly stick it into the aperture field of a
+graphic object, and instead need to wrap it inside an :py:class:`.ApertureMacroInstance` first. 
+
+Excellon vs. Gerber
+-------------------
+
+Excellon files use the same graphic object classes as Gerber files. Inside an Excellon file, only
+:py:class:`~.graphic_objects.Line`, :py:class:`~.graphic_objects.Arc` and :py:class:`.Flash` are allowed. Lines and arcs map to milled
+Excellon slots. Excellon drills are mapped to :py:class:`.Flash` instances. 
+
+Excellon drills are internally handled using a special :py:class:`.ExcellonTool` aperture class. When you put a
+:py:class:`.GraphicObject` from an Excellon file into a Gerber file, these become circular apertures. You can also take
+objects from an Excellon file and put them into a Gerber file if they have a simple :py:class:`.CircleAperture`. Copying
+objects with other apertures into an Excellon file will raise an error when saving. 
+