gitea-admin/gh-christianlouis-leagueledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive documentation for LeagueLedger

Browse Source 
- Created architecture overview in development/architecture.md
- Added installation guide in getting-started/installation.md
- Developed user guide with detailed instructions in user-guide/overview.md, user-guide/teams.md, user-guide/qr-codes.md
- Implemented social login setup documentation in social_login_setup.md
- Updated index.md to include links to new documentation sections
- Configured mkdocs.yml for site structure and theme
- Added requirements.txt for documentation dependencies
This commit is contained in:
Christian Krakau-Louis
2025-04-15 12:32:03 +02:00
parent 7323c12168
commit 6306abf6d9
26 changed files with 3350 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide/overview.md
+125
View File
@@ -0,0 +1,125 @@
# LeagueLedger User Guide
Welcome to the LeagueLedger User Guide. This section provides detailed instructions on how to use LeagueLedger as an end user.
## Getting Started as a User
### Creating an Account
To use LeagueLedger, you'll first need to create an account:
1. Navigate to the [LeagueLedger homepage](http://localhost:8000)
2. Click on the "Sign Up" or "Register" button
3. Fill in the required information:
- Username
- Email address
- Password
4. Complete the verification process through the email sent to your address
5. Log in with your new credentials
### Logging In
You can log in using:
- Your username and password
- Social login (if configured by your administrator) via Google, GitHub, Microsoft, and other supported providers
## Core Features
### User Dashboard
After logging in, you'll see your dashboard with:
- Your personal points totals
- Teams you're a member of
- Recent activities and achievements
- Upcoming events
- Quick access to common actions
### Teams
Teams are the core organizational unit in LeagueLedger:
- **Joining Teams**: Find teams through search or receive invitations
- **Creating Teams**: Start your own team and invite others
- **Team Management**: View team statistics, achievements, and members
### QR Codes and Points
Points in LeagueLedger are typically awarded through QR codes:
- **Scanning QR Codes**: Use the scan feature to capture QR codes at events
- **Points History**: Track all your earned points and achievements
- **Team Points**: View how your contributions affect team standings
### Events
LeagueLedger tracks various events:
- **Upcoming Events**: See what events are scheduled
- **Event Registration**: Sign up for events individually or as a team
- **Event Attendance**: Check in to events using QR codes
### Leaderboards
Track standings and achievements:
- **Individual Leaderboards**: See how you rank among all participants
- **Team Leaderboards**: View team rankings
- **Event-specific Leaderboards**: Standings for particular events
## User Settings
### Profile Management
Customize your experience through the profile settings:
1. Navigate to "My Account" or "Settings"
2. Update your:
- Profile picture
- Personal information
- Email preferences
- Notification settings
### Account Security
Manage your account security:
- Change your password
- Enable/disable social login connections
- View active sessions
## Navigation Guide
### Main Menu
The main menu provides access to all major features:
- **Dashboard**: Your personal overview
- **Teams**: Access to teams you belong to
- **Events**: Upcoming and past events
- **QR Scanner**: Tool to scan QR codes
- **Leaderboards**: Overall standings
- **Profile**: Your personal settings
### Mobile Navigation
On mobile devices, the menu is accessible through the hamburger icon (≡) in the top corner.
## Getting Help
If you encounter any issues while using LeagueLedger:
- Check the FAQ section
- Contact your organization's administrator
- Submit a support request through the "Help" section
## Next Steps
For more detailed information about specific features, please refer to the following guides:
- [User Accounts](user-accounts.md): Detailed account management information
- [Teams](teams.md): Complete team management guide
- [QR Codes](qr-codes.md): Everything about the QR code system
- [Points & Achievements](points-and-achievements.md): How points and achievements work
- [Leaderboard](leaderboard.md): Understanding the leaderboard system
- [Events](events.md): Comprehensive events guide
docs/user-guide/qr-codes.md
+241
View File
@@ -0,0 +1,241 @@
# QR Codes System
The QR code system is a core feature of LeagueLedger, enabling easy point attribution and event participation tracking. This guide explains how QR codes work in the system and how to use them effectively.
## Overview
LeagueLedger's QR code system allows organizers to:
- Create point-valued QR codes that users can scan
- Group codes into sets for specific events or purposes
- Track redemption and usage statistics
- Print codes for physical distribution
Users can scan these codes to:
- Earn points for themselves or their team
- Check in to events
- Claim achievements
- Verify attendance
## QR Code Types
LeagueLedger supports several types of QR codes:
### Point Value Codes
These codes represent specific point values that are awarded when scanned:
- **Standard Points**: Fixed point values (e.g., 5, 10, 25 points)
- **Variable Points**: Point values that may fluctuate based on factors like time, location, or number of scans
- **Team-Specific Points**: Codes that only award points to specific teams
### Functional Codes
These codes trigger specific actions in the system:
- **Check-In Codes**: For event attendance verification
- **Achievement Codes**: Unlock specific achievements when scanned
- **Registration Codes**: Link to team registration or event signup
- **Information Codes**: Open detailed information about an event or challenge
## Scanning QR Codes
### Mobile Scanning
To scan a QR code using a mobile device:
1. Log in to LeagueLedger on your mobile browser
2. Navigate to the "Scan" option in the menu
3. Allow camera permissions if prompted
4. Point your camera at the QR code
5. The system will automatically detect and process the code
6. A confirmation screen will display the points awarded or action taken
### Desktop Scanning
For desktop users with webcams:
1. Log in to LeagueLedger
2. Click on the "Scan QR Code" option in the navigation menu
3. Allow camera permissions when prompted
4. Position the QR code in front of your webcam
5. The system will process the code once detected
### Upload Scanning
If you have a QR code image file:
1. Go to the "Scan QR" page
2. Select the "Upload QR Code Image" option
3. Choose the image file from your device
4. Submit the image for processing
## Creating QR Codes (Administrators)
Administrators can create QR codes through the admin panel:
### Creating Individual QR Codes
1. Navigate to the Admin Panel > QR Codes
2. Click on "Create New QR Code"
3. Fill in the required information:
- Point value
- Description
- Redemption limit (how many times it can be scanned)
- Expiration date (if applicable)
- Team restrictions (if applicable)
4. Click "Generate Code"
5. The new QR code will be displayed and added to the database
### Creating QR Code Sets
For organizing multiple codes together:
1. Go to Admin Panel > QR Codes > QR Sets
2. Select "Create New Set"
3. Provide a name and description for the set
4. Choose the number of codes to generate in this set
5. Configure the point values (fixed, random, or custom distribution)
6. Set any common properties (expiration, redemption limits)
7. Generate the set
### Printing QR Codes
To print physical copies of QR codes:
1. Go to Admin Panel > QR Codes or QR Sets
2. Select the code(s) you wish to print
3. Click "Print QR Codes"
4. Choose the print format:
- Standard layout
- Compact grid
- Labels
- Individual cards
5. Configure printing options (size, labels, etc.)
6. Click "Generate Printable PDF"
7. Print the generated document
## Managing QR Codes
### Monitoring Usage
Track QR code usage through the Admin Panel:
1. Go to Admin Panel > QR Codes
2. View the list of codes with usage statistics
3. Click on a specific code for detailed redemption history
4. See who scanned the code, when, and how many points were awarded
### Deactivating Codes
To disable a QR code:
1. Navigate to Admin Panel > QR Codes
2. Find the code you wish to deactivate
3. Click "Edit" or select the code
4. Toggle the "Active" status to inactive
5. Save changes
The code will remain in the system for record-keeping but can no longer be redeemed.
### Modifying Codes
To change a QR code's properties:
1. Go to Admin Panel > QR Codes
2. Select the code to modify
3. Click "Edit"
4. Update the desired properties
5. Save changes
!!! warning "Active Codes"
Modifying the point value or redemption rules of already-distributed codes may cause confusion for users. Consider creating new codes instead of changing existing ones.
## Best Practices
### Security
- **Regenerate Codes Regularly**: Create new QR codes for each event to prevent reuse
- **Limit Redemptions**: Set appropriate scan limits to prevent abuse
- **Verify Location**: For important events, consider enabling location verification
- **Monitor Unusual Activity**: Check for patterns that might indicate QR code sharing
### Organization
- **Meaningful Names**: Use descriptive names for QR sets and codes
- **Color Coding**: Consider printing different point values on different colored paper
- **Tracking Identifiers**: Include visible IDs on printed codes for easy reference
- **Backup Copies**: Maintain digital backups of all generated codes
### Distribution
- **Strategic Placement**: Place higher-value codes in less obvious locations
- **Staffed Stations**: For high-value codes, consider having staff present
- **Time-Limited Availability**: Make codes available only during specific periods
- **Progressive Difficulty**: Structure code placement so finding codes gets progressively harder
## Troubleshooting
### Common Issues
#### QR Code Not Scanning
If a code isn't being recognized:
- Ensure adequate lighting
- Hold the device steady and at an appropriate distance
- Make sure the code isn't damaged or obscured
- Try using the image upload option instead
#### Points Not Awarded
If scanning succeeds but points aren't awarded:
- Check if the user is logged in
- Verify if the code has reached its redemption limit
- Check if the code has expired
- Confirm the user hasn't already scanned this code
#### Printing Problems
For issues with printed QR codes:
- Ensure printer resolution is adequate (300 DPI minimum recommended)
- Avoid scaling codes to very small sizes
- Print test codes and verify they scan correctly before mass production
- Use high-contrast printing (black on white background)
## Use Cases and Examples
### Hunt/Challenge Events
Create a scavenger hunt by placing QR codes throughout a venue:
- Place codes with varying point values in different locations
- Create clues that lead participants to code locations
- Track progress and award bonus points for completing the full hunt
### Attendance Tracking
Use QR codes for verifying attendance:
- Generate unique check-in codes for each event
- Place codes at event entrances
- Have participants scan on arrival
- Generate attendance reports from the admin panel
### Reward Programs
Implement a progressive reward system:
- Issue QR codes for completing certain tasks
- Create achievement sets that unlock when specific codes are collected
- Offer special rewards for collecting complete sets
## Next Steps
- [Team Management](teams.md): Learn how teams accumulate and manage points
- [Events](events.md): How to integrate QR codes with events
- [Points & Achievements](points-and-achievements.md): More about the points system
- [QR Code Management](../administration/qr-code-management.md): Advanced administration of QR codes
docs/user-guide/teams.md
+300
View File
@@ -0,0 +1,300 @@
# Teams
Teams are a core feature of LeagueLedger, allowing users to form groups that compete and collaborate. This guide explains how to create, join, and manage teams within the system.
## Teams Overview
In LeagueLedger, teams provide a way for users to:
- Collaborate toward common goals
- Compete against other teams
- Share resources and achievements
- Track collective progress
Each team has:
- A unique name and profile
- A team owner (creator by default)
- Team members with different roles
- A team points total (sum of members' contributions)
- Team-specific achievements and stats
## Creating a Team
### Basic Team Creation
To create a new team:
1. Log in to your LeagueLedger account
2. Navigate to the "Teams" section from the main menu
3. Click the "Create New Team" button
4. Fill in the required information:
- Team name (unique within the system)
- Short description
- Team logo (optional)
5. Select team visibility:
- Public: Visible to all users
- Private: Visible only to members and invitees
6. Choose join settings:
- Open: Anyone can join
- Request: Users can request to join
- Invite-only: Only invited users can join
7. Click "Create Team"
You'll automatically become the team owner with full administrative privileges.
### Team Settings
After creating a team, you can configure additional settings:
1. Go to your team page
2. Click on "Team Settings" (visible to team owners and admins)
3. Customize options such as:
- Banner image
- Team biography
- Contact information
- Social media links
- Team rules or guidelines
## Joining Teams
### Finding Teams to Join
To discover teams you might want to join:
1. Navigate to the "Teams" section
2. Click on "Browse Teams" or "Join Team"
3. Browse available teams with options to:
- Search by name or keywords
- Filter by various criteria
- Sort by size, activity, or points
4. Click on any team to view its details
### Joining an Open Team
For teams with "Open" join settings:
1. View the team details page
2. Click the "Join Team" button
3. You'll immediately be added as a member
### Requesting to Join
For teams with "Request" join settings:
1. View the team details page
2. Click "Request to Join"
3. Optional: Add a short message to the team owner
4. Submit your request
5. Wait for approval from a team admin or owner
6. You'll receive a notification when your request is approved or denied
### Joining via Invitation
If you receive a team invitation:
1. Check your notifications or email for the invitation
2. Click the invitation link
3. Review the team details
4. Click "Accept" to join or "Decline" to refuse
## Team Roles and Management
### Team Roles
LeagueLedger teams have a hierarchy of roles:
- **Owner**: The team creator with full control
- **Admin**: Can manage members and some team settings
- **Member**: Regular team participant
- **Guest**: Limited temporary access (optional feature)
### Team Member Management
As a team owner or admin, you can manage team members:
1. Go to your team page
2. Click on "Manage Members"
3. From this panel, you can:
- Invite new members
- Remove existing members
- Change member roles
- Review join requests
- Send team announcements
### Transferring Ownership
To transfer team ownership:
1. Go to "Team Settings" > "Advanced"
2. Select "Transfer Ownership"
3. Choose a team member to become the new owner
4. Confirm the transfer
!!! warning "Irreversible Action"
Transferring ownership cannot be undone. The new owner will have complete control over the team.
## Team Activities
### Team Points
Teams earn points when members:
- Scan QR codes
- Complete challenges
- Participate in events
- Earn achievements
- Contribute through other scoring actions
The team leaderboard reflects the cumulative points of all team members.
### Team Achievements
Teams can unlock special achievements based on:
- Total team points milestones
- Full team participation in events
- Completing special team challenges
- Consistent activity over time
Team achievements are displayed on the team profile and contribute to the team's prestige.
### Team Events
Teams can participate in events together:
1. Find an event in the "Events" section
2. Register as a team (by team owner/admin)
3. Coordinate team member participation
4. Earn team points through event activities
## Team Communication
### Team Chat
Teams have access to a built-in chat system:
1. Go to your team page
2. Click on the "Team Chat" tab
3. Send messages visible to all team members
4. Share updates, strategies, or coordinate activities
### Announcements
Team owners and admins can make official announcements:
1. Go to "Manage Members"
2. Select "Create Announcement"
3. Write your message
4. Choose notification options
5. Publish to all members
## Advanced Team Features
### Team Statistics
View detailed team performance:
1. Go to your team page
2. Select the "Statistics" tab
3. Explore metrics such as:
- Points over time
- Member contributions
- Achievement progress
- Event participation
- Comparison with other teams
### Team Challenges
Some events feature special team challenges:
- Collaborative tasks requiring multiple team members
- Inter-team competitions
- Timed challenges with team scoring
- Special team-only QR codes
### Private Team QR Codes
Team owners can create team-specific QR codes:
1. Go to "Team Settings" > "QR Codes"
2. Select "Create Team QR"
3. Configure the code settings
4. Generate and share with team members only
These codes may offer bonus points or special achievements when scanned by team members.
## Leaving or Dissolving a Team
### Leaving a Team
To leave a team you're a member of:
1. Go to the team page
2. Click on "Team Settings" or "Manage Membership"
3. Select "Leave Team"
4. Confirm your decision
!!! note "Team Owner"
If you're the team owner, you must first transfer ownership before leaving.
### Dissolving a Team
To completely dissolve a team (owner only):
1. Go to "Team Settings" > "Advanced"
2. Select "Dissolve Team"
3. Read the warning about this irreversible action
4. Enter your password to confirm
5. The team will be permanently removed
## Best Practices
### For Team Owners
- Establish clear team goals and guidelines
- Regularly communicate with team members
- Recognize individual contributions
- Delegate responsibilities to trusted admins
- Keep team information and graphics up-to-date
### For Team Members
- Regularly check team announcements
- Coordinate with teammates for events
- Share strategies for finding and scanning QR codes
- Help recruit quality new members
- Represent your team positively in competitions
## Troubleshooting
### Common Issues
#### Can't Find a Team
If you can't locate a specific team:
- Check if you spelled the team name correctly
- The team might be set to private visibility
- The team may have been dissolved
#### Can't Join a Team
If you're unable to join:
- The team might be invite-only
- Your request might be pending approval
- You may have reached the maximum number of teams you can join
- The team might have reached its member capacity
#### Points Not Showing for Team
If points aren't appearing:
- There may be a delay in point calculation
- Verify that your individual points are displaying correctly
- Check that you're properly affiliated with the team
## Next Steps
- [QR Codes](qr-codes.md): Learn how to earn points through QR codes
- [Points & Achievements](points-and-achievements.md): Understand the points system
- [Events](events.md): Discover how to participate in events as a team
- [Team Management](../administration/team-management.md): For administrators managing multiple teams