Improve architecture document

Author: alcaeus

src/Codec/architecture.md

@@ -1,14 +1,17 @@
 # Converting BSON data through codecs
 
-The codec system is a more advanced way to convert BSON data to native types and back, designed for libraries with more
-advanced use cases, e.g. object mappers. It is designed to decouple the serialisation logic from the data model,
-allowing for more flexible implementations.
+Codecs provide a more flexible way to convert BSON data to native types and back and address most of the shortcomings of
+the previous type map system. The codec system is designed to be used by libraries that need to convert BSON data into
+native types, for example object mappers. Unlike the type map system, codecs allow converting any BSON type to a native
+type directly when reading data from the database. Together with lazy decoding of BSON structures, this allows
+for a more flexible and efficient way to handle BSON data.
 
 ## Encoders and Decoders
 
-The codec interface is split into two smaller interfaces: encoders and decoders. Both interfaces are marked as internal,
-as users are only expected to interact with the Codec interface. The interfaces are typed using Psalm generics, allowing
-for better type checking when they are used. Without type annotations, the interfaces are equivalent to the following:
+The codec interface is comprised by two smaller interfaces: encoders and decoders. Both interfaces are marked as
+internal, as users are only expected to interact with the Codec interface. The interfaces are typed as generics through
+`@template` annotations, allowing for better type checking when they are used. Without type annotations, the interfaces
+are equivalent to the following:
 
 ```php
 namespace MongoDB\Codec;
@@ -32,7 +35,7 @@ interface Encoder
 }
 ```
 
-## Codec interface
+## Codec Interface
 
 The `Codec` interface combines decoding and encoding into a single interface. This will be used for most values except
 for documents where a more specific `DocumentCodec` is provided.
@@ -44,23 +47,16 @@ encode or decode a value only if it is supported. If it is not supported, the or
 ```php
 namespace MongoDB\Codec;
 
-/**
- * @psalm-template BSONType
- * @psalm-template NativeType
- * @template-extends Decoder<BSONType, NativeType>
- * @template-extends Encoder<BSONType, NativeType>
- */
 interface Codec extends Decoder, Encoder
 {
 }
 ```
 
-## Document codec
+## Document Codec
 
 The document codec is special as it is guaranteed to always encode to a BSON document instance and decode to a PHP
-object. Document codecs can be provided to a `MongoDB\Collection` instance to have it automatically decode data read
-from the database. Likewise, any supported value is encoded before writing to the database in `insert` and `replace`
-operations.
+object. Document codecs will be used by `MongoDB\Collection` instances to automatically decode BSON data into PHP
+objects when reading data, and to encode PHP objects when inserting or replacing data.
 
 ```php
 namespace MongoDB\Codec;
@@ -76,11 +72,29 @@ interface DocumentCodec extends Codec
 }
 ```
 
-## Using codecs
+## Built-in codecs
+
+By default, two codecs are provided: an `ArrayCodec` and an `ObjectCodec`. These two codecs are used to recursively
+encode and decode values in arrays and `stdClass` instances, respectively. When encoding or decoding an object,
+`ObjectCodec` only handles public properties of the object and ignores private and protected properties.
+
+## Future Work
+
+### Using Codecs
+
+The `MongoDB\Collection` class and all operations that work with documents now take a `codec` option. This option is
+passed along to the various operations that already take a `typeMap` option. Collections only support a `DocumentCodec`
+instance to guarantee that data always encodes to a BSON document and decodes to a PHP object.
+
+All operations that return documents will use the codec to decode the documents into PHP objects. This includes
+the various `find` and `findAndModify` operations in collections as well as the `aggregate` and `watch` operations in
+collections, databases, and the client object itself.
+
+When writing data, any operation that takes an entire document will use the codec to automatically encode the document.
+This is limited to `insertOne`, `insertMany`, `replaceOne`, and `findOneAndReplace` operations in collections. `update`
+operations will not use the codec to encode documents, as they only support update operators and can't work with the
+entire document.
 
-The `MongoDB\Collection` class and all operations that work with documents now take a `codec` option. This can be
-an instance of a `DocumentCodec` that will be used to encode documents (for insert and replace operations) and decode
-them into PHP objects when reading data.
 
 ### Codecs and type maps
 
@@ -96,9 +110,3 @@ this case, the type map is used. The precedence order is as follows:
 Codecs are not inherited from the client or the database object, as they are purely used for operations that return
 documents. However, database- or client-level aggregation commands will take an operation-level codec option to
 decode the resulting documents.
-
-## Built-in codecs
-
-By default, two codecs are provided: an `ArrayCodec` and an `ObjectCodec`. These two codecs are used to recursively
-encode and decode values in arrays and `stdClass` instances, respectively. `ObjectCodec` only handles public properties
-in objects and ignores other properties.