Skip to content

Home

Jump to bottom
Siyâvash edited this page Dec 16, 2025 · 1 revision

ExpoScholar Wiki

Welcome to the ExpoScholar documentation wiki. This wiki provides comprehensive documentation for the ExpoScholar educational exhibition management platform.

Quick Navigation

About ExpoScholar

ExpoScholar is an educational exhibition management platform that demonstrates integrated web and mobile application development using modern software engineering practices. The system consists of a Django-based server application and a Flutter-based mobile client, designed to work together in offline-capable workflows with automatic synchronization.

Current Version: v0.9.3-beta+3
License: GNU GPLv3+
Status: Active development

System Overview

ExpoScholar consists of three primary components:

  1. Server Application - Django 5.2-based REST API and administrative interface
  2. Mobile Application - Flutter-based cross-platform client for Android and iOS
  3. Infrastructure - Deployment configurations for Docker, Kubernetes, and cloud environments

Key Features

Server:

  • RESTful API for mobile client synchronization
  • HTML5-only administrative interface (no JavaScript dependencies)
  • User authentication and authorization
  • Subscription management and billing
  • Booth and item management
  • Order processing
  • Audit logging
  • Payment processing integration (Stripe, PayPal)

Mobile:

  • Offline-first data storage using SQLite
  • Automatic background synchronization
  • Camera-based media capture
  • Booth and item management
  • Order creation and management
  • Configurable server endpoints
  • Diagnostic and debugging tools

Infrastructure:

  • Docker containerization for server and mobile components
  • Kubernetes deployment manifests
  • Monitoring stack (Prometheus, Alertmanager, Grafana)
  • Automated backup and restore procedures
  • Security hardening configurations
  • Autoscaling policies
  • Terraform infrastructure as code

Quick Start

Prerequisites

  • Operating System: GNU/Linux or macOS (Windows via WSL)
  • Python: 3.11 or later
  • Flutter SDK: 3.38.3 or later
  • Java: 17 (for Android builds)
  • Android SDK: 36
  • Android NDK: 27.0.12077973
  • Git and GNU Make

Installation

The fastest way to get started:

git clone git@github.com:mkhellat/exposcholar.git
cd exposcholar
./setup install

This will:

  • Validate system requirements
  • Install Python dependencies
  • Set up Flutter dependencies
  • Configure development environment

Verify Installation

./setup check

Start Development Servers

./setup start-server    # Start Django server at http://localhost:8000
./setup start-mobile    # Start Flutter app

Documentation Structure

Primary Documentation

The project includes comprehensive Texinfo documentation that can be built into multiple formats:

  • Info format: View with info exposcholar after building
  • HTML format: Single-file HTML manual
  • PDF format: Printable PDF manual

Build documentation with:

./setup docs              # Build Info and HTML
./setup docs-pdf          # Build PDF (requires TeX)

Component Documentation

  • Server: See server/README.md
  • Mobile: See mobile/README.md
  • Infrastructure: See infrastructure/README.md

Development Workflow

  1. Install dependencies: ./setup install
  2. Start services: ./setup start-server and ./setup start-mobile
  3. Access web UI: http://localhost:8000
  4. Run tests: ./setup test
  5. Build artifacts: ./setup build-apk or ./setup build-aab

Testing

Server Tests

./setup test-server
# or
cd server && python manage.py test

Mobile Tests

./setup test-mobile
# or
cd mobile && flutter test

Coverage

cd server && python manage.py test --coverage
cd mobile && flutter test --coverage

Building Applications

Android APK

./setup build-apk [--release] [--obfuscate]

Android App Bundle (for Google Play)

./setup build-aab [--release] [--obfuscate]

iOS Application

./setup build-ios [--release] [--obfuscate]

Project Structure

exposcholar/
├── server/            # Django apps, config, requirements, templates
├── mobile/            # Flutter sources, platform folders, tests
├── infrastructure/    # Docker, Kubernetes, monitoring, Terraform, etc.
├── scripts/           # Setup, debug, deployment, utility scripts
├── tests/             # Server, mobile, and integration suites
├── docs/              # Documentation (Texinfo source and generated files)
├── Makefile           # Root orchestration targets
└── setup              # Guided CLI for installs and operations

Infrastructure Highlights

  • Docker: Containerization for server and mobile components
  • Kubernetes: Deployment manifests for production clusters
  • Monitoring: Prometheus, Alertmanager, and Grafana stack
  • Backup: Automated backup and restore procedures
  • Security: Network policies, RBAC, Pod Security Standards
  • Autoscaling: Horizontal and vertical pod autoscaling
  • Terraform: Infrastructure as code for cloud environments

Troubleshooting

Common Issues

Installation Problems:

  • Run ./setup check to validate prerequisites
  • Ensure Python 3.11+ and Flutter 3.38.3+ are installed
  • Verify Android SDK and NDK versions match requirements

Development Issues:

  • Server won't start: Check migrations with python manage.py migrate
  • Mobile build fails: Run flutter clean and flutter pub get
  • Synchronization not working: Verify server endpoint configuration

Deployment Issues:

  • Check Docker/Kubernetes logs
  • Verify environment variables
  • Review security settings

For detailed troubleshooting, see the Troubleshooting page.

Contributing

We welcome contributions! Please see the Contributing page for guidelines on:

  • Code style and standards
  • Commit message format
  • Testing requirements
  • Pull request process

Support

  • Documentation: See docs/ directory for comprehensive Texinfo manual
  • Issues: File issues via the repository issue tracker
  • License: See LICENSE file for complete GPLv3 terms
  • Contributors: See AUTHORS file

Educational Mission

ExpoScholar exists to provide a transparent, high-quality learning artifact for students and researchers studying integrated web/mobile systems. Every script, manifest, and configuration is written with the intent to explain professional workflows.

Additional Resources

Last Updated: 2025-11-25
ExpoScholar Version: v0.9.3-beta+3

Clone this wiki locally