From b2d61892a8049d5f587d7936797e079631b2d089 Mon Sep 17 00:00:00 2001
From: Eduardo Marques <eduardomarqs1@gmail.com>
Date: Tue, 6 May 2025 02:39:31 +0200
Subject: [PATCH] doc: include base documentation

---
 README.md           |  34 +++++++++++++
 docs/basic-guide.md | 117 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 docs/basic-guide.md

diff --git a/README.md b/README.md
index e69de29..7d33f5c 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,34 @@
+DynamoPHP
+================
+![License](https://img.shields.io/github/license/edumarques/dynamophp)
+![Build Status](https://github.com/edumarques/dynamophp/actions/workflows/base.yml/badge.svg)
+![Coverage](https://codecov.io/gh/edumarques/dynamophp/graph/badge.svg?token=E20936W7JD)
+
+---
+
+**DynamoPHP** is a strongly-typed, attribute-based Object Data Mapper for Amazon DynamoDB. It is built on top of modern
+PHP, which enable definition of entities using PHP 8+ attributes and interaction with DynamoDB using a clean, expressive
+API.
+
+Inspired by data mappers like [Doctrine](https://www.doctrine-project.org) and modeled after patterns in libraries such
+as [TypeDORM](https://github.com/typedorm/typedorm).
+
+## Installation
+
+```
+composer require edumarques/dynamophp
+```
+
+## Documentation
+
+Documentation is an ongoing effort. Our docs will continue to evolve as the project grows—contributions and
+improvements are welcome and encouraged!
+
+- [Basic Usage Guide](docs/basic-guide.md)
+
+## Contributing
+
+Contributors are always welcome! For more information on how you can contribute, please read
+our [contribution guideline](CONTRIBUTING.md).
+
+For any questions, feel free to reach out to me directly by email: [eduardomarqs1@gmail.com](mailto:eduardomarqs1@gmail.com).
diff --git a/docs/basic-guide.md b/docs/basic-guide.md
new file mode 100644
index 0000000..127ae68
--- /dev/null
+++ b/docs/basic-guide.md
@@ -0,0 +1,117 @@
+# Basic Usage Guide
+
+**DynamoPHP** is a lightweight, attribute-based _Object Data Mapper_ designed to simplify development with Amazon
+DynamoDB. Inspired by modern data-mapping libraries, it brings a familiar, expressive API to PHP for modeling DynamoDB
+entities.
+
+## Contents
+
+- [Installation](#installation)
+- [Concepts](#concepts)
+- [Getting Started](#getting-started)
+
+## Installation
+
+Install **DynamoPHP** via Composer:
+
+```bash
+composer require edumarques/dynamophp
+```
+
+## Concepts
+
+### Entity
+
+An Entity in **DynamoPHP** is a PHP class that maps to a single item (also known as document or row) in a DynamoDB
+table. Entities are defined using PHP attributes.
+
+### Attribute
+
+An Attribute is an item's property (also known as field or column) that should be persisted in a DynamoDB table.
+Attributes are defined using PHP attributes.
+
+### PartitionKey and SortKey
+
+Compose the Primary Key of items, and reference how items are stored in and retrieved from the table. They are defined
+by fields in Entity's PHP attribute.
+
+### Entity Manager
+
+The Entity Manager is the main interface for performing operations like saving, fetching, querying, and deleting items
+from DynamoDB.
+
+## Getting Started
+
+To get started with **DynamoPHP**, you basically need to:
+
+1. Define your entity model using attributes.
+2. Create an instance of the EntityManager.
+3. Use the entity manager to read/write data.
+
+Here is an example of a simple entity:
+
+```php
+use EduardoMarques\DynamoPHP\Attribute\Attribute;
+use EduardoMarques\DynamoPHP\Attribute\Entity;
+use EduardoMarques\DynamoPHP\Attribute\PartitionKey;
+use EduardoMarques\DynamoPHP\Attribute\SortKey;
+
+#[Entity(
+    table: 'users',
+    partitionKey: new PartitionKey(['id']),
+    sortKey: new SortKey(['createdAt'])
+)]
+class User
+{
+    #[Attribute]
+    public string $id;
+    
+    #[Attribute(name: 'name')]
+    public string $fullName;
+
+    #[Attribute]
+    public DateTimeInterface $createdAt;
+}
+```
+
+Each entity must:
+
+- Declare a table name.
+- Define a partition key and, if the table schema requires, a sort key, via PartitionKey and SortKey objects in their
+  respective fields.
+- Optionally, set persistent properties with #[Attribute].
+
+Create an instance of EntityManager using the factory:
+
+```php
+use EduardoMarques\DynamoPHP\ODM\EntityManagerFactory;
+
+$entityManager = EntityManagerFactory::create([
+    'region' => 'eu-central-1',
+    'endpoint' => 'http://localhost:4566',
+    'credentials' => ['key' => 'key', 'secret' => 'secret'],
+]);
+```
+
+This internally creates a DynamoDB client using the AWS SDK and wires up all dependencies.
+
+Run the operations you need, for instance:
+
+```php
+// Create/update entity
+$user = new User();
+$user->id = 'user-123';
+$user->fullName = 'John Doe';
+$user->createdAt = new DateTime();
+
+$entityManager->put($user);
+
+// Fetch entity by primary key
+$entity = $entityManager->get(User::class, [
+    'id' => 'user-123',
+    'createdAt' => new DateTime(),
+]);
+```
+
+That's it! The Entity Manager will handle all the wiring of dependencies and operations, including serialization and
+communication with the DynamoDB client.