Skip to content

Commit 36b63c3

Browse files
wojciechkrzoswojciechkrzos
committed
feat: repo structure and hitherto docs
1 parent 9e126de commit 36b63c3

11 files changed

Lines changed: 222 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Glosownik Documentation
2+
3+
This repository contains version-controlled project documentation.
4+
5+
## Sections
6+
7+
- [Actors](./actors/)
8+
- [Requirements](./requirements/)
9+
- [Architecture](./architecture/)
10+
- [Processes](./processes/)
11+
- [Sequence diagrams](./sequences/)
12+
- [User stories](./stories/)

‎actors/admin.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Admin
2+
3+
Admin manages voting configuration and reviews voting results.
4+
5+
## Goals
6+
7+
- Create and configure voting sessions.
8+
- Review results after voting ends.

‎actors/voter.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Voter
2+
3+
Voter participates in available voting sessions.
4+
5+
## Goals
6+
7+
- Sign in securely.
8+
- Cast a valid vote.

‎architecture/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Architecture
2+
3+
Architecture is described with [C4 model](https://c4model.com/).
4+
5+
- [c4.dsl](./c4.dsl)

‎architecture/c4.dsl‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
workspace "Glosownik" "Architecture model for the Glosownik voting system." {
2+
model {
3+
admin = person "Admin"
4+
voter = person "Voter"
5+
6+
auth = softwareSystem "3rd Party Auth" {
7+
tags "External System"
8+
}
9+
10+
glosownik = softwareSystem "Glosownik"
11+
12+
admin -> glosownik "Manages votes and views results"
13+
voter -> glosownik "Signs in and votes"
14+
glosownik -> auth "Authenticates users with"
15+
}
16+
17+
views {
18+
systemContext glosownik "c1-system-context" {
19+
include *
20+
autoLayout lr
21+
}
22+
23+
styles {
24+
element "Person" {
25+
shape Person
26+
background #08427b
27+
color #ffffff
28+
}
29+
30+
element "Software System" {
31+
background #1168bd
32+
color #ffffff
33+
}
34+
35+
element "External System" {
36+
background #999999
37+
color #ffffff
38+
}
39+
}
40+
}
41+
}

‎processes/voting-flow.bpmn‎

Whitespace-only changes.

‎requirements/functional.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Functional Requirements
2+
3+
## Voting
4+
5+
| ID | Name | Description |
6+
| --- | --- | --- |
7+
| FR-101 | Casting Votes | The system allows eligible voters to cast a single vote per question in an active voting session. A voter cannot vote more than once on the same question. |
8+
| FR-102 | Adding Questions During Voting | The system allows admins to add new questions to an active voting session. Added questions apply only to voters who have not yet cast their vote. Users who have already voted are not required to vote again. |
9+
| FR-103 | Vote Anonymity | The system does not associate cast votes with individual voter identities. Admins can only view aggregated results. |
10+
11+
## Session Management
12+
13+
| ID | Name | Description |
14+
| --- | --- | --- |
15+
| FR-201 | Session Configuration | The system allows admins to create, edit, and delete voting sessions, including setting their start and end time and assigning questions. |
16+
| FR-202 | Results Inspection | The system allows admins to view voting results at any time during and after a voting session. |
17+
| FR-203 | Results Visibility | The system allows admins to configure whether results are visible to voters, and if so, whether during or only after the voting session ends. |
18+
| FR-204 | Session Lifecycle | The system allows admins to manually open, close, and archive voting sessions. Closed sessions do not accept new votes. |
19+
20+
## User Management
21+
22+
| ID | Name | Description |
23+
| --- | --- | --- |
24+
| FR-301 | Manual User Management | The system allows admins to manually add and remove users from the administration panel. |
25+
| FR-302 | CSV User Import | The system allows admins to import users from a CSV file. |
26+
| FR-303 | Excel User Import | The system allows admins to import users from an Excel file. |
27+
| FR-304 | User Import From Previous Sessions | The system allows admins to import the user list from a previous voting session. |
28+
29+
## Authorization
30+
31+
| ID | Name | Description |
32+
| --- | --- | --- |
33+
| FR-401 | Admin-Based Authorization | The system allows users to be authorized manually by an admin. This is the baseline authorization method. |
34+
| FR-402 | External Authorization | The system allows users to be authorized through an external provider [TBD]. This method can be used as an alternative to admin-based authorization (FR-401). |

‎requirements/non-functional.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Non-Functional Requirements
2+
3+
## Group 1
4+
5+
| ID | Name | Description |
6+
| --- | --- | --- |
7+
| NFR-101 | --- | --- |
8+
9+
## Group 2
10+
11+
| ID | Name | Description |
12+
| --- | --- | --- |
13+
| NFR-201 | --- | --- |

‎sequences/authentication.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Authentication Sequence
2+
3+
```mermaid
4+
sequenceDiagram
5+
autonumber
6+
7+
participant Voter
8+
participant Client
9+
participant Auth as Authorization Service
10+
participant Signer as Blind Signature Server
11+
participant VoteServer as Voting Server
12+
participant Database
13+
participant Tally as Tallying Service
14+
15+
Note over Client,Signer: RSA signing key pair is pre-configured. Public key is known to the client. Private key is kept by the signer.
16+
Note over Client,Tally: Election encryption public key is known to the client. Private key is kept only for tallying.
17+
18+
Voter->>Client: Start voting process
19+
Client->>Auth: Authenticate voter
20+
Auth-->>Client: Authorization completed
21+
22+
Client->>Client: Generate token m
23+
Client->>Client: Generate blinding factor r
24+
Client->>Client: Blind token using m, r and signer public key
25+
26+
Client->>Signer: Send blinded token
27+
Signer->>Auth: Check voter eligibility
28+
Auth-->>Signer: Voter eligible and not used yet
29+
30+
Signer->>Signer: Sign blinded token with private key
31+
Signer->>Auth: Mark authorization as used
32+
Signer-->>Client: Return signed blinded token
33+
34+
Client->>Client: Unblind signed token using r
35+
Client->>Client: Obtain signed anonymous voting token
36+
37+
Voter->>Client: Select vote
38+
Client->>Client: Encrypt vote with election public key
39+
40+
Client->>VoteServer: Submit encrypted vote and signed token
41+
VoteServer->>VoteServer: Verify token signature with signer public key
42+
VoteServer->>Database: Check whether token was already used
43+
44+
alt Token is valid and unused
45+
VoteServer->>Database: Store token hash and encrypted vote
46+
VoteServer-->>Client: Vote accepted
47+
else Token is invalid or already used
48+
VoteServer-->>Client: Vote rejected
49+
end
50+
51+
Tally->>Database: Retrieve encrypted votes
52+
Tally->>Tally: Decrypt votes with election private key
53+
Tally->>Tally: Count votes
54+
```

‎stories/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# User Stories
2+
3+
This section contains user stories and story maps.
4+
5+
- [Story map](./story-map.md)

0 commit comments

Comments
 (0)