diff --git a/README.md b/README.md
new file mode 100644
index 00000000..8a0bd1f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,169 @@
+## 1. Creating the City Model from a GeoJSON File
+
+Start by using the `GeometryFactory` class to create a city model from a GeoJSON file. This class reads building geometries and attributes from the file and constructs a city model.
+
+```python
+city = GeometryFactory(
+  "geojson",
+  input_file,
+  height_field="height",
+  year_of_construction_field="contr_year",
+  function_field="function_c",
+  adjacency_field="adjacency",
+  function_to_hub=Dictionaries().montreal_function_to_hub_function
+).city
+```
+
+- `"geojson"`: Specifies the format of the input file.
+- `input_file`: The path to your GeoJSON file.
+- `height_field="height"`: The attribute in the GeoJSON file that contains the building height.
+- `year_of_construction_field="contr_year"`: The attribute for the building's year of construction.
+- `function_field="function_c"`: The attribute for the building's function or usage.
+- `adjacency_field="adjacency"`: The attribute indicating whether the building is attached or detached.
+- `function_to_hub`: A dictionary that maps the building functions to standardized functions used by HUB.
+
+The `city` object now contains all the buildings from the GeoJSON file with their associated attributes.
+
+---
+
+## 2. Enriching the City with Construction Details
+
+Use the `ConstructionFactory` to enrich the city model with construction details and calculation of the thermal zones and total floor area.
+
+```python
+ConstructionFactory('nrcan', city).enrich()
+```
+
+- `'nrcan'`: Specifies the source of construction data, in this case, NRCan.
+- `city`: The city model created in the previous step.
+---
+## 3. Assigning Energy Demands Using Archetypes
+
+Finally, we assign energy demands to each building using the `ResultFactory` class and an archetype-based demand model. This basically maps buildings to predefined archetypes and assigning corresponding energy demand profiles.
+
+```python
+ResultFactory('archetypes', city, demand_file).enrich()
+```
+- `'archetypes'`: Specifies the handler we are using which in this case is archetype-based demand model.
+- `city`: The city.
+- `demand_file`: The path to the CSV file containing the archetype demand profiles.
+---
+
+## 4. Rules for Finding Archetypes and Assigning Demands
+
+This mapping is based on the following building attributes:
+
+- **Function**
+- **Height**
+- **Adjacency**: Whether the building is attached or is detached.
+- **Year of Construction**
+
+### **Mapping Rules**:
+
+Based on the building's function, height, and adjacency:
+
+- **Residential Buildings** ('residential', 'multifamily house', 'single family house'):
+  - **Single Family House**:
+    - Height less than 6 meters.
+    - Adjacency: 'detached'.
+    - `usage = 'Single Family'`.
+  - **Row House**:
+    - Height less than 6 meters.
+    - Adjacency: 'attached'.
+    - `usage = 'Row house'`.
+  - **Duplex/Triplex**:
+    - Height between 6 and 10 meters.
+    - Adjacency: 'detached'.
+    - `usage = 'Duplex/triplex'`.
+  - **Small MURBs** (Multi-Unit Residential Buildings):
+    - Height between 6 and 10 meters.
+    - Adjacency: 'attached'.
+    - `usage = 'Small MURBs'`.
+  - **Medium MURBs**:
+    - Height between 10 and 15 meters.
+    - `usage = 'Medium MURBs'`.
+  - **Large MURBs**:
+    - Height greater than 15 meters.
+    - `usage = 'Large MURBs'`.
+
+- **Office Buildings** ('office', 'office and administration'):
+  - `usage = 'Office'`.
+
+- **Commercial Buildings** ('commercial', 'retail shop without refrigerated food', 'retail shop with refrigerated food', 'stand alone retail', 'strip mall'):
+  - If adjacency is 'attached':
+    - `usage = 'Commercial attached'`.
+  - Else:
+    - `usage = 'Commercial detached'`.
+
+#### Determine Building Vintage (`vintage`):
+
+Based on the building's year of construction:
+
+- **Pre-1947**:
+  - `year <= 1947`.
+  - `vintage = 'Pre 1947'`.
+- **1947-1983**:
+  - `1947 < year <= 1983`.
+  - `vintage = '1947-1983'`.
+- **1984-2010**:
+  - `1983 < year <= 2010`.
+  - `vintage = '1984-2010'`.
+- **Post-2010**:
+  - `year > 2010`.
+  - `vintage = 'Post 2010'`.
+
+Combine usage and vintage to create the key:
+
+```python
+archetype_key = f"{usage} {vintage}"
+```
+
+This key is used to look up the corresponding demand profiles in the archetype demand file.
+
+---
+
+### Assigning Demands:
+
+1. **Lookup Demand Profiles**:
+
+   Using the `archetype_key`, retrieve the hourly demand profiles from the `demand_file`. Each archetype has associated hourly demands for different energy uses.
+
+2. **Scale Demands by Floor Area**:
+
+   Multiply the demand values by the building's total floor area.
+
+3. **Assign Demands to Building**:
+
+   Set the building's demand attributes:
+
+   ```python
+   building.heating_demand = [value * area for value in demand['Heating']]
+   building.cooling_demand = [value * area for value in demand['Cooling']]
+   building.domestic_hot_water_heat_demand = [value * area for value in demand['DHW']]
+   building.appliances_electrical_demand = [value * area for value in demand['Equipment']]
+   building.lighting_electrical_demand = [value * area for value in demand['Lighting']]
+   ```
+
+---
+
+### Example:
+
+For a residential building with the following attributes:
+- **Function**: 'residential'
+- **Height**: 9 meters
+- **Adjacency**: 'attached'
+- **Year of Construction**: 1986
+
+#### **Mapping Steps**:
+
+1. **Usage**:
+   - Height is between 6 and 10 meters.
+   - Adjacency is 'attached'.
+   - Therefore, `usage = 'Small MURBs'`.
+
+2. **Vintage**:
+   - Year is 1986, which falls in 1984-2010.
+   - Therefore, `vintage = '1984-2010'`.
+
+3. **Archetype Key**:
+   - `archetype_key = 'Small MURBs 1984-2010'`.
\ No newline at end of file