Skip to content

Commit 8419373

Browse files
authored
Merge pull request #54 from Lab-Lab-Lab/update_docs
move the concluding readme docs into main readme
2 parents e734fb6 + ce2a8bb commit 8419373

File tree

15 files changed

+233
-233
lines changed

15 files changed

+233
-233
lines changed

.python-version

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.13.1

.vscode/settings.json

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
{
22
"python.analysis.extraPaths": [
33
"./thoughtswap"
4-
]
4+
],
5+
"cSpell.words": [
6+
"thoughtswap"
7+
],
8+
"isort.check": true
59
}

README.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,112 @@
11
# ThoughtSwap
22

3+
## Project Overview
4+
5+
Thought Swap is a discussion facilitation app where a facilitator sends prompts to participants, who submit anonymous responses that are later redistributed for small-group discussion.
6+
7+
**Github repository:** https://github.com/Lab-Lab-Lab/ThoughtSwap
8+
9+
**Key technologies:**
10+
- Django (backend)
11+
- Django Channels (WebSocket communication)
12+
- HTML, JavaScript (frontend templates)
13+
14+
**Core features:**
15+
- Prompt creation, management, and reuse
16+
- Anonymous response submission
17+
- Response “swap” feature for small-group discussion
18+
- Facilitator dashboard with course and session controls
19+
20+
## What Has Been Accomplished
21+
22+
- Set up Django backend and database models
23+
- Course, Enrollment, Prompt, Session, PromptUse, Thought
24+
- Integrated WebSocket support (channels) for real-time updates to both the facilitator and participant
25+
- Facilitators can switch their course from three states: Active, Draft, and Inactive
26+
- Facilitators can create prompts ahead of time
27+
- Facilitators can send prompts to participants to respond to
28+
- Facilitators can disperse responses using the “swap” feature
29+
- Participants can join a new course via a room code
30+
- Participants can view the current prompt
31+
- Participants can respond to the current prompt
32+
- Participants can receive a thought to discuss
33+
34+
## Key Decisions Made (with Explanations)
35+
36+
- **What is PromptUse**
37+
The `PromptUse` model acts as a connection between a prompt and a session. It allows the same prompt to be reused across multiple sessions while keeping track of responses specific to each session. This design improves flexibility by avoiding duplicate prompt entries and enables better tracking of when and where prompts were used.
38+
39+
- **Why there are different HTML templates**
40+
I separated the HTML templates into `facilitator_session.html`, `participant_session.html`, and `teacher_dashboard.html` to clearly divide the interfaces by user role. Each role has very different needs:
41+
42+
- **Intended functionality of restrictions around swapping**
43+
When swapping responses, the system should ensure that:
44+
- Each participant receives a response from someone else (not their own)
45+
- There must be at least two active student who have responded
46+
- If there are more students than responses, responses are randomly duplicated
47+
48+
49+
## Known Issues or Bugs
50+
51+
- Swapping thoughts needs to be more robust
52+
- Late joiners need to be fully addressed
53+
- Safety and robustness of user contributions has not been fully tested
54+
55+
## Next Steps
56+
57+
- Front-end styling + UX
58+
- Facilitator's ability to create a new course
59+
- Facilitator's ability to create a new session
60+
- “Demo mode,” where the facilitator and/or participants need not create a lasting account
61+
- Functionality for late joiners
62+
- When swapping: if one author is more prolific for a certain prompt, before assigning all their thoughts to others, first ensure that each author's thoughts are assigned (and specifically to authors (users who have submitted for this prompt))
63+
- Somehow allow for the participants indicate their thoughts about the distributed thought
64+
- Start having semantic analysis
65+
- Find some way to track how the discussion went (Form for after the discussion?)
66+
- Participant view for the facilitator
67+
- Offer rich text editor in prompt composition and thought composition
68+
69+
## Important Files / Code to Know
70+
71+
- `facilitator_session.html`
72+
This is the main interface for facilitators. It allows them to:
73+
- Write and send prompts
74+
- Swap anonymous participant responses
75+
- Access the prompt bank
76+
- View active and past prompts
77+
It also includes WebSocket logic to handle live updates from the server.
78+
79+
- `participant_session.html`
80+
This is the participant view during a session. Participants can:
81+
- See the current prompt
82+
- Submit their responses
83+
- Receive a swapped response to discuss
84+
It connects to the WebSocket server to listen for prompt updates and swapped thoughts.
85+
86+
- `teacher_dashboard.html`
87+
This is the dashboard where teachers manage their courses and sessions.
88+
- Shows all enrolled courses
89+
- Lets the teacher switch session states (Active, Inactive, Draft)
90+
- Displays and manages the prompt bank, including adding new prompts
91+
92+
- `models.py`
93+
Contains all the Django data models, including:
94+
- Course, Enrollment, Prompt, Session, PromptUse, Thought
95+
96+
- `views.py`
97+
Contains the Django views that:
98+
- Handle requests and render the pages
99+
- Manage course state changes
100+
- Provide data to the templates
101+
102+
- `consumers.py`
103+
Contains the Django Channels consumers that:
104+
- Handle WebSocket connections
105+
- Receive and send real-time events like new prompts, new thoughts, swaps, and prompt bank data
106+
107+
108+
# ThoughtSwap as an instance of Cookiecutter Django
109+
3110
A project,
4111

5112
[![Built with Cookiecutter Django](https://img.shields.io/badge/built%20with-Cookiecutter%20Django-ff69b4.svg?logo=cookiecutter)](https://github.com/cookiecutter/cookiecutter-django/)

config/asgi.py

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import os
22
from pathlib import Path
3-
from django.core.asgi import get_asgi_application # num 1 of 4ish that have to
3+
from django.core.asgi import get_asgi_application # num 1 of 4ish that have to
4+
45
# be in the correct order https://forum.djangoproject.com/t/i-get-the-error-apps-arent-loaded-yet-when-publishing-with-daphne/30320/14
56
from channels.routing import ProtocolTypeRouter, URLRouter
67
from channels.security.websocket import AllowedHostsOriginValidator
@@ -21,13 +22,14 @@
2122
sett = env("DJANGO_SETTINGS_MODULE")
2223
print("DJANGO_SETTINGS_MODULE before setting in asgi", sett)
2324
# os.environ.setdefault("DJANGO_SETTINGS_MODULE", "thoughtswap.settings")
24-
os.environ.setdefault("DJANGO_SETTINGS_MODULE", sett) # num2
25-
26-
django_asgi_app = get_asgi_application() # num 3
25+
os.environ.setdefault("DJANGO_SETTINGS_MODULE", sett) # num2
2726

28-
from thoughtswap.thoughtswap.routing import websocket_urlpatterns # 4a
29-
from thoughtswap.chat.routing import websocket_urlpatterns as thoughtswap_chat_routing #4b
27+
django_asgi_app = get_asgi_application() # num 3
3028

29+
from thoughtswap.thoughtswap.routing import websocket_urlpatterns # 4a
30+
from thoughtswap.chat.routing import (
31+
websocket_urlpatterns as thoughtswap_chat_routing,
32+
) # 4b
3133

3234

3335
application = ProtocolTypeRouter(

config/settings/base.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# ruff: noqa: ERA001, E501
22
"""Base settings to build other settings files upon."""
33

4-
54
from pathlib import Path
65

76
import environ

config/settings/test.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
from .local import * # noqa: F403
66
from .local import TEMPLATES
77
from .local import env
8+
89
# GENERAL
910
# ------------------------------------------------------------------------------
1011
# https://docs.djangoproject.com/en/dev/ref/settings/#secret-key

config/urls.py

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,8 @@
2929
# ...
3030
# Media files
3131
*static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT),
32-
path('prompt-bank/', views.prompt_bank_view, name='prompt_bank'),
33-
path('add-prompt-to-bank/', views.add_prompt_to_bank, name='add_prompt_to_bank'),
34-
32+
path("prompt-bank/", views.prompt_bank_view, name="prompt_bank"),
33+
path("add-prompt-to-bank/", views.add_prompt_to_bank, name="add_prompt_to_bank"),
3534
]
3635

3736

docs/thoughtswap.md

Lines changed: 0 additions & 106 deletions
This file was deleted.

thoughtswap/chat/apps.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22

33

44
class ChatConfig(AppConfig):
5-
default_auto_field = 'django.db.models.BigAutoField'
6-
name = 'chat'
5+
default_auto_field = "django.db.models.BigAutoField"
6+
name = "chat"

thoughtswap/chat/views.py

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,3 @@ def index(request):
99

1010
def room(request, room_name):
1111
return render(request, "chat/room.html", {"room_name": room_name})
12-

0 commit comments

Comments
 (0)