diff --git a/README.md b/README.md
index 55a4072..0b98eca 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,10 @@ Elevator application for controlling `n` elevators across `m` floors
 in a distributed fashion, implemented in Elixir.
 
 ## Documentation
-
-See `doc/index.html` for module documentation.
-
+```bash
+mix docs
+```
+See design description and diagrams in `docs/`.
 
 ## Running nodes
 
diff --git a/docs/Final Report.pdf b/docs/Final Report.pdf
new file mode 100644
index 0000000..de43d99
Binary files /dev/null and b/docs/Final Report.pdf differ
diff --git a/docs/diagrams/HallButtonFSM.png b/docs/diagrams/HallButtonFSM.png
deleted file mode 100644
index 4e33424..0000000
Binary files a/docs/diagrams/HallButtonFSM.png and /dev/null differ
diff --git a/docs/diagrams/hall_button_fsm.puml b/docs/diagrams/hall_button_fsm.puml
deleted file mode 100644
index 474c398..0000000
--- a/docs/diagrams/hall_button_fsm.puml
+++ /dev/null
@@ -1,35 +0,0 @@
-@startuml HallButtonFSM
-title Hall Button — cyclic-counter consensus
-
-' States
-[*] --> Unknown : System start
-note right of Unknown
-Can go to any state by
-receiving from another node
-end note
-
-Idle: counter = 0
-Idle: entry/ Turn off light
-
-Pending: counter = 1
-Pending: entry/ calculate score
-Pending: list_nodes_in_pending
-
-Scoring: counter = 2
-Scoring: score_map
-
-Confirmed: counter = 2
-Confirmed: entry/ Turn on light
-' note left of Agreed
-' All nodes have been updated to decided
-' Largest score starts serving
-' end note
-
-' Transitions
-Unknown --> Pending : Button pressed
-Idle -down-> Pending : Button pressed
-Pending -down-> Scoring : Received from all
-Scoring -up-> Confirmed : Score map full
-Confirmed -right-> Idle : Arrived at floor 
-
-@enduml
diff --git a/docs/diagrams/hall_order_fsm.puml b/docs/diagrams/hall_order_fsm.puml
new file mode 100644
index 0000000..ba348db
--- /dev/null
+++ b/docs/diagrams/hall_order_fsm.puml
@@ -0,0 +1,17 @@
+@startuml HallOrderFSM
+title Hall Order FSM
+
+[*] --> Idle
+Idle --> Pending : button_press
+Pending --> Handling : barrier full /\n calculate cost
+Handling --> Arrived : arrived
+Arrived --> Idle : barrier full
+
+state Idle : no known order\nlight OFF
+state Pending : barrier: nodes in pending\nlight OFF
+state Handling : cost map\nlight ON
+state Arrived : barrier: nodes in arrived\nlight OFF
+
+' receive_external needs to be described in some additionl text
+
+@enduml
diff --git a/docs/diagrams/modules.png b/docs/diagrams/modules.png
deleted file mode 100644
index 80ee484..0000000
Binary files a/docs/diagrams/modules.png and /dev/null differ
diff --git a/docs/diagrams/modules.puml b/docs/diagrams/modules.puml
index c8762e8..6d118eb 100644
--- a/docs/diagrams/modules.puml
+++ b/docs/diagrams/modules.puml
@@ -1,84 +1,29 @@
 @startuml modules
-title Modules
-' Simple class diagram for the elevator modules
-
-package SingleElevator {
-    interface Driver {
-        + motor
-        + lights
-        + buttons
-        + floor sensors
-    }
-
-    class FSM {
-        - elev_state
-        - my_orders
-        + init()
-        + on_arrival(floor)
-        + on_door_timeout()feat: ping function and docs for each function
-        + on_request_button(button)
-    }
-
-    class Controller {
-        - button_poller()
-        - order_poller()
-        + read_floor_sensor()
-        + read_all_buttons()
-        + clear_all_lights()
-        + clear_light(button)
-        + open_door()
+' title Modules
+' high-level module architecture
+
+skinparam componentStyle rectangle
+' skinparam linetype ortho
+left to right direction
+
+package Stateful {
+    component FSM.State
+    component Orders {
+        component HallOrders
+        component CabOrders
     }
-
-    class Requests {
-        + should_stop(elev_state, orders, floor)
-        + choose_direction(elev_state, orders)
-        + should_clear_immidiately(elev_state, floor)
-    }
-
-    FSM --> Requests
-    FSM --> Controller
-    Controller --> Driver
 }
 
-class Communicator {
-    - broadcast_state()
-    - receive_state()
-    + who_is_alive()
+package Stateless {
+    component FSM.Transition
+    component Communicator
+    component Hardware
 }
 
-class CabOrders {
-    - orders: map
-    - version: uint64
-    + cast: receive_state()
-    + cast: update_orders(newOrders, version)
-    + cast: clear_floor(floor)
-    + call: button_press(floor)
-    + call: get_orders()
-}
-
-class HallOrders {
-    - orders: map
-    - count: uint
-    - others
-    + cast: arrived_floor(floor, dir)
-    + cast: receive_state(orders)
-    + cast: btn_press(floor, dir)
-    + call: get_orders()
-    + call: get_my_orders()
-}
-
-class Scoring {
-    + score_request(elevator_state, orders, new_request)
-}
-
-Controller --> HallOrders
-Controller --> CabOrders
-
-Communicator <--> CabOrders
-
-HallOrders --> Scoring
-HallOrders --> CabOrders
-HallOrders <--> Communicator
-
+Hardware --> FSM.State : Sensor updates
+Hardware --> Orders : Button presses
+FSM.Transition --> FSM.State : State updates
+FSM.Transition --> Orders : Floor arrival
+Communicator --> Orders : External orders
 
 @enduml