Skip to content

Commit 7527d0f

Browse files
PelayoPerezPelayoPerez
committed
Architecture constraints and architecture solutions documentation in progress
1 parent 1d394f3 commit 7527d0f

File tree

2 files changed

+205
-0
lines changed

2 files changed

+205
-0
lines changed

‎docs/src/02_architecture_constraints.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,78 @@ ifndef::imagesdir[:imagesdir: ../images]
33
[[section-architecture-constraints]]
44
== Architecture Constraints
55

6+
=== Technical Constraints
7+
8+
|===
9+
|Constraint |Explanation
10+
11+
|Web application must be implemented in TypeScript/JavaScript
12+
|The frontend and external API are required to be developed using TypeScript/JavaScript as specified in the assignment.
13+
14+
|Bot logic must be implemented in Rust
15+
|The game engine responsible for move suggestion and win detection must be developed as a separate Rust module.
16+
17+
|Communication between subsystems via JSON using YEN notation
18+
|The web application and the Rust service must exchange data using JSON messages following the YEN game notation defined in the assignment.
19+
20+
|Service-oriented architecture
21+
|The Rust module must expose its functionality through a web service interface callable by the web application.
22+
23+
|Use of Firebase as the database
24+
|User data, match history, and statistics must be stored in Firebase, as chosen by the team.
25+
26+
|Deployment on a cloud platform
27+
|The system must be publicly accessible. The backend services will be deployed on a cloud provider (e.g., Vercel, Railway, or Azure).
28+
29+
|Public external API for bots
30+
|The system must expose a documented API allowing external bots to access game data and play matches.
31+
32+
|Browser-based execution
33+
|The frontend must run in standard modern web browsers without requiring special installations.
34+
|===
35+
36+
---
37+
38+
=== Organizational Constraints
39+
40+
|===
41+
|Constraint |Explanation
42+
43+
|Assignment requirements define core functionality
44+
|The system must implement at least the classic version of Game Y with player-vs-machine mode and variable board size.
45+
46+
|Public deployment required
47+
|The application must be accessible through the web as part of the evaluation criteria.
48+
49+
|Documentation must follow arc42
50+
|Architecture documentation must comply with the arc42 structure provided by the course.
51+
52+
|Quality requirements for evaluation
53+
|The project must include testing (unit, integration, and e2e), CI/CD, monitoring, and proper repository management.
54+
55+
|Team-based academic project
56+
|Decisions must consider limited time, resources, and team size typical of a university assignment.
57+
|===
58+
59+
---
60+
61+
=== Conventions and Standards
62+
63+
|===
64+
|Constraint |Explanation
65+
66+
|Use of YEN notation for game state
67+
|All game states exchanged between components must follow the defined YEN notation format.
68+
69+
|REST-style API with JSON
70+
|All external and internal services will communicate using JSON over HTTP.
71+
72+
|Version control with Git
73+
|All source code and documentation will be managed using a Git repository.
74+
75+
|Code quality and testing practices
76+
|The project must include automated tests and follow agreed coding standards.
77+
|===
678

779
ifdef::arc42help[]
880
[role="arc42help"]

‎docs/src/09_architecture_decisions.adoc‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,139 @@ ifndef::imagesdir[:imagesdir: ../images]
33
[[section-design-decisions]]
44
== Architecture Decisions
55

6+
This section documents the most important architectural decisions made during the development of the system.
7+
Each decision includes its context, the chosen option, and the rationale.
8+
9+
---
10+
11+
=== ADR-001: Separation into Web Application and Rust Game Engine
12+
13+
*Status:* Accepted
14+
15+
*Context:*
16+
The assignment requires the system to be composed of at least two subsystems:
17+
- A web application implemented in TypeScript.
18+
- A game logic module implemented in Rust.
19+
20+
*Decision:*
21+
The system will follow a **service-oriented architecture** where:
22+
- The web application handles the user interface, API, and user management.
23+
- The Rust module provides game logic (win detection and move suggestion) through a web service.
24+
25+
*Rationale:*
26+
- Required by the assignment.
27+
- Separates concerns between UI and game logic.
28+
- Rust provides high performance for algorithmic computations.
29+
30+
*Consequences:*
31+
- Requires inter-service communication via HTTP and JSON.
32+
- Adds deployment and integration complexity.
33+
34+
---
35+
36+
=== ADR-002: Communication via JSON using YEN Notation
37+
38+
*Status:* Accepted
39+
40+
*Context:*
41+
The assignment specifies that both subsystems must communicate using JSON messages following YEN notation.
42+
43+
*Decision:*
44+
All communication between the web application and the Rust service will use:
45+
- HTTP requests
46+
- JSON payloads
47+
- YEN notation for game states
48+
49+
*Rationale:*
50+
- Mandatory requirement from the assignment.
51+
- JSON is simple, widely supported, and easy to debug.
52+
53+
*Consequences:*
54+
- Both services must implement serialization and validation of YEN data.
55+
- Changes to the notation would affect both subsystems.
56+
57+
---
58+
59+
=== ADR-003: Use of Firebase as the Database
60+
61+
*Status:* Accepted
62+
63+
*Context:*
64+
The system requires user registration, match history, and statistics storage.
65+
66+
Possible options:
67+
- Self-hosted database (PostgreSQL, MySQL)
68+
- Managed cloud database
69+
- Firebase
70+
71+
*Decision:*
72+
Use **Firebase** as the main data storage solution.
73+
74+
*Rationale:*
75+
- Fully managed service with minimal setup.
76+
- Built-in authentication and real-time database features.
77+
- Reduces infrastructure and maintenance effort.
78+
- Suitable for small-to-medium academic projects.
79+
80+
*Consequences:*
81+
- Vendor lock-in to Firebase ecosystem.
82+
- Limited flexibility compared to self-hosted databases.
83+
- Requires internet connectivity for all operations.
84+
85+
---
86+
87+
=== ADR-004: Cloud Deployment of the Application
88+
89+
*Status:* Accepted
90+
91+
*Context:*
92+
The assignment requires the system to be publicly accessible via the web.
93+
94+
Possible hosting options:
95+
- Local/on-premise server
96+
- Traditional VM hosting
97+
- Cloud platform (Vercel, Railway, Azure)
98+
99+
*Decision:*
100+
Deploy the system on a cloud platform, with the final choice between:
101+
- Vercel
102+
- Railway
103+
- Azure
104+
105+
*Rationale:*
106+
- Meets the public deployment requirement.
107+
- Simplifies infrastructure management.
108+
- Enables CI/CD and easy scaling.
109+
110+
*Consequences:*
111+
- Requires configuration for cloud environments.
112+
- Possible cost considerations.
113+
- Platform-specific deployment setups.
114+
115+
---
116+
117+
=== ADR-005: External REST API for Bots
118+
119+
*Status:* Accepted
120+
121+
*Context:*
122+
The assignment requires an API that allows external bots to interact with the system and play games.
123+
124+
*Decision:*
125+
Expose a REST-style HTTP API that:
126+
- Accepts JSON requests.
127+
- Uses YEN notation for game state.
128+
- Provides endpoints for game interaction.
129+
130+
*Rationale:*
131+
- REST is simple and widely supported.
132+
- Easy integration with external bots.
133+
- Matches the JSON communication requirement.
134+
135+
*Consequences:*
136+
- Requires proper authentication and validation.
137+
- Must be fully documented.
138+
6139

7140
ifdef::arc42help[]
8141
[role="arc42help"]

0 commit comments

Comments
 (0)