diff --git a/README.md b/README.md
index ea042b2..aee02e8 100755
--- a/README.md
+++ b/README.md
@@ -1,27 +1,44 @@
 # fiveTargetGame
 
-Set of two applications targetting Microchip AVR chips, implementing shooting game.
-The game is made of two parts: the *gun* and the *targets*.
-There is up to four players, trying to shoot five targets in a row, using 5 tries.
+Set of two applications targetting Atmel/Microchip [ATMega328P](https://www.microchip.com/en-us/product/atmega328p), implementing shooting game.
 
-At some point, games ends and the player with best shot/hit ratio wins the game.
+Using a *gun*, users tries to hit *targets*.
+The game is up to four players: yellow, green, red and blue.
+There are 5 targets.
 
-## target
-The **target** application manages player points and communicate with an Android application implemented on top of [Bluetooth Electronics](https://www.keuwl.com/apps/bluetoothelectronics/) application. It manages the game logic and player points.
+### Game mode
 
+#### Biathlon like
+Each player turn gives 5 shots. Player tries to hit each target. Total number of shoots is counted, as well as successfull hits.
 
-## Gun
+## Functional details
+### target
+
+The **target** application manages player points and turns. It communicates with an Android application implemented on top of [Bluetooth Electronics](https://www.keuwl.com/apps/bluetoothelectronics/) application. It manages the game logic and player points.
+
+
+### Gun
 The **Gun** application manages the gun. Using two buttons, it allows:
 
 | Press |      Button 1    |             Button 2           |
 |-------|------------------|--------------------------------|
-| short | power on / shoot | Begin new round (give 5 shots) |
+| short |       shoot      | Begin new round (give 5 shots) |
 | long  |     power off    | continuous laser (calibration) |
 
 Gun application manages following outputs:
 * Laser
 * vibrator
-* led
+* 128x32 I²C display 
+
+## Architecture details
+
+Some parts of the projet, implementing logic, can be used on both native and target platform.
+All that code is represented in the "domain" package below.
+
+Both **target** and **Gun** application are run both native and cross environment. The current
+target hardware for both is the [ATMega328p](https://www.microchip.com/en-us/product/atmega328p) chip from Atmel/Microchip.
+To facilitate testing and extension, user interface (Gui) and hardware abstraction (HAL) are provided using interfaces. Implementation exists for native and cross (i.e. testing) environments.
 
-For more details of gun logic, see test cases.
+Note: The *BTEGui* implementation can be used in native environment. Based on plain string exchange, if it may be difficult to interpret.
 
+![Architecture overview](architecture.png)
diff --git a/architecture.mermaid b/architecture.mermaid
new file mode 100644
index 0000000..a469976
--- /dev/null
+++ b/architecture.mermaid
@@ -0,0 +1,84 @@
+classDiagram
+
+    Game "4" *--> User
+    BTEGui ..|> ITargetGui
+
+    TargetApp *--> "1" Game
+    TargetApp *--> "1" 328TargetsHal
+    TargetApp *--> "1" BTEGui
+    
+    TestHal ..|> ITargetHal
+    TestGui ..|> ITargetGui
+    ConsoleTargets *--> "1" Game
+    ConsoleTargets *--> "1" TestGui
+    ConsoleTargets *--> "1" TestHal
+    ConsoleGun *--> "1" Gun
+    ConsoleGun *--> "1" TestHal
+
+    GunApp *--> "1" Gun
+    GunApp *--> "1" 328GunHal
+
+    328TargetsHal ..|> ITargetHal
+    328GunHal ..|> IGunHal
+
+    namespace ATMega328{
+        
+        class 328TargetsHal{
+        }
+
+        class 328GunHal{
+        }
+    }
+
+    namespace Domain {
+
+        class Game{
+        }
+
+        class User{
+        }
+
+        class BTEGui{
+        }
+
+        class Gun{
+        }
+
+        class ITargetHal{
+            <<interface>>
+        }
+
+        class IGunHal{
+            <<interface>>
+        }
+
+        class ITargetGui{
+            <<interface>>
+        }
+    }
+
+
+    namespace Native_Environment{
+
+        class ConsoleTargets{
+        }
+        class ConsoleGun{
+        }
+
+        class TestHal{
+
+        }
+
+        class TestGui{
+
+        }
+    }
+
+
+    namespace Cross_Environment {
+        class TargetApp{
+        }
+
+        class GunApp{
+        }
+    }
\ No newline at end of file
diff --git a/architecture.png b/architecture.png
new file mode 100644
index 0000000..f886c80
Binary files /dev/null and b/architecture.png differ