add 'legal_path' creation to INSTALL script
[brisk.git] / doc / ARCHITECTURE.txt
1 ===== Sparse documentation about Brisk. =====
2
3 User cleanup:
4   spush::garbage_manager()
5     if (user->the_end)
6         close opened socket
7
8     brisk->users_cleanup() to reset all users with the_end set
9
10 ==== brisk/table/user relationships ====
11
12 === points management ===
13
14 read from db:
15   * continue a match
16   * calculate placings
17   * calculate explain
18
19 write to db:
20   * finish a game
21
22 === in the room ===
23
24 // when standup
25 bri->user[user_idx] = user
26 user->idx      = user_idx
27 user->idx_orig = user_idx
28
29 // when sitdown
30 table->player[player_idx] = user_idx
31 user->table_pos = player_idx
32
33 === in the game ===
34
35 bin5->user[user_idx] = user
36 table->player[player_idx] = user_idx
37 user->table_pos = player_idx
38
39
40 Many things aren't documented at all, but I start with authentication workflow.
41
42 ==== MODIFY USERS TABLE ====
43
44 === PHP CODE ===
45
46 web/Obj/dbase_base.phh
47   function LoginDBItem -> args & body
48   function LoginDBItemFromRecord -> args & body
49
50 === SQL CODE ===
51 sql/sql.d/nnn-name-patch.sql
52
53
54 AUTHENTICATION WORKFLOW
55
56 --- CLI ------------
57 index.php:
58   onsubmit="return j_login_manager(this);" ->
59             sync xhr(index_wr.php?mesg=getchallenge&cli_name=<username>)
60
61 --- SRV ------------
62   GET index_wr.php send the string: "1|<tokens>"
63
64 --- CLI ------------
65   POST index.php with passid_private field equal to calcMD5(tokens[1]+calcMD5(form.elements['passid'].value))
66   add_user -> validate_name, login_verify
67
68
69 ===== Game Lifecycle =====
70
71 -> bin5/index_wr.php + argz[0] == 'logout'
72    - bri->table_wakeup($user)
73      - set users subst to "shutdowner" and "shutdowned"
74      - save this: "gst.st_loc++; the_end=true; window.onbeforeunload = null; \
75                    window.onunload = null; document.location.assign("../index.php");" 
76        in user->comm var for client xhr
77      - set $bri->the_end = TRUE
78
79
80 -> index.php  (after verify session value: ~L250)
81   - garbage_manager(TRUE)
82     - align many status var with briskin5 user values
83     - room_join_wakeup()
84
85 ==== Chunk flow ====
86
87
88 $ret = $user->maincheck($old_stat, $old_subst, $old_step, $this->rd_stat, $this->rd_subst, $this->rd_step,
89                         $splashdate, $table_idx, $table_token))
90 $user->rd_transp->chunk($this->rd_scristp++, $ret);
91
92
93 ===== New users workflow =====
94
95          UserA                 UserB                      Admin
96 -------------------------------------------------------------------------
97       guarante UserB
98            |
99            v
100       Save on mail
101          table,
102       email to UserB
103     (Disabled, MAILED)
104 -------------------------------------------------------------------------
105                            Receive email
106                            to check address
107                                  |
108                                  v
109                            Click on link
110                                  |
111                                  v
112                            Check on mail
113                                table,
114                            update user status,
115                            delete mail rec
116                           (Disabled, TOBECHK)
117 -------------------------------------------------------------------------
118                                                        admin panel
119                                                        accept user
120                                                             |
121                                                             v
122                                                      send email with
123                                                      password,
124                                                      update user status
125                                                       (Normal, NONE)
126 -------------------------------------------------------------------------
127                            Receive email
128                            with password
129 -------------------------------------------------------------------------