ExpoScholar

ExpoScholar is an educational exhibition-management platform that pairs a Django server with a Flutter mobile client. The repository demonstrates modern build orchestration, offline-first workflows, and security-minded infrastructure patterns. The current reference version is v0.9.3-beta+3.

Overview

• Django REST API with HTML5-only administrative UI (no JavaScript)
• Flutter app for booth/item capture, offline storage, and smart sync
• Automated setup script plus Makefile for repeatable environments
• Infrastructure examples spanning Docker, Kubernetes, monitoring, autoscaling, and security controls
• Test suites and tooling that illustrate practical QA workflows

Architecture Snapshot

Server

• Django 4.x, Django REST Framework, SQLite (dev) with pluggable DBs
• Authentication, subscription, audit logging, and admin workflows
• HTML5 native templates and CSS-only interactions

Mobile

• Flutter 3.32+ with Provider-based state management
• SQLite persistence, background synchronization, and camera capture
• Configurable server endpoint, diagnostics panel, multiple build modes

Infrastructure

• Dockerfiles for server and Flutter web, Compose-based dev stack
• Kubernetes manifests for deployments, services, ingress, autoscaling
• Monitoring bundle (Prometheus, Alertmanager, Grafana) and backup jobs
• Terraform blueprints for cloud environments

Tooling

Setup CLI (./setup)

• ./setup install — full environment provisioning
• ./setup server / ./setup mobile — component-specific setup
• ./setup start-server, ./setup start-mobile — dev servers and QEMU
• ./setup build-apk, ./setup build-aab, ./setup build-ios — release artifacts with optional obfuscation flags
• ./setup monitoring|autoscaling|security|backup|ci-cd — infra helpers
• ./setup test-server, ./setup test-mobile, ./setup test — test entry points with graceful handling of known Flutter WebSocket issues
• ./setup docs, ./setup docs-info, ./setup docs-html, ./setup docs-pdf — build documentation from Texinfo source

Makefile

• Mirrors the setup CLI for users who prefer GNU Make targets
• Adds Docker/Kubernetes testing (make docker-test, make infra-test-k8s)
• Provides lint/format, dependency refresh, and cleanup commands
• Documentation build targets (make docs, make docs-info, make docs-html, make docs-pdf)

Getting Started

Prerequisites

• Linux or macOS with bash, Git, and GNU Make
• Python 3.11+, pip, and virtualenv support
• Flutter SDK 3.32+, Java 17, Android SDK 36, Android NDK 27.0.12077973
• Optional: QEMU for Android VM testing, Xcode for iOS builds
• Optional: Texinfo tools (makeinfo or texi2any) for building documentation

Quick Install

cd exposcholar
./setup install

Granular Setup

./setup server
./setup mobile

Using Make

make help
make setup
make test

Android VM (optional)

Use the ./setup start-mobile automation or follow the QEMU instructions embedded in the setup script to create an Android x86 QCOW2 disk and boot an emulator that listens on localhost ADB ports.

Development Workflow

1. Install dependencies (./setup install).
2. Start services: ./setup start-server and ./setup start-mobile.
3. Access the web UI at http://localhost:8000 and the API under /api/.
4. Build artifacts with the setup script or Makefile targets.
5. Follow the release checklist embedded in the tooling comments when preparing tagged builds.

Testing

Django

./setup test-server
# or
cd server && python manage.py test apps.accounts.tests apps.exposcholar.tests --verbosity=2

Flutter

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

When the Flutter harness encounters the known WebSocketException flakiness, rerun flutter analyze or follow the manual widget testing instructions in the mobile test utilities.

Coverage

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

Project Layout

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)
│   ├── exposcholar.texi  # Main Texinfo manual source
│   └── texinfo/       # Organized chapter and appendix files
├── Makefile           # Root orchestration targets
├── setup              # Guided CLI for installs and operations
└── README.md          # This file

Infrastructure Highlights

• Docker build targets (make docker-build*) and Compose helpers for full-stack local runs
• Kubernetes resources for deployments, services, ingress, autoscaling, and network policies
• Monitoring stack manifests plus Alertmanager and Grafana dashboards
• Backup cron jobs and restoration scripts for PostgreSQL and Redis
• Terraform modules defining VPC, compute, and storage primitives

Troubleshooting Tips

1. Run ./setup check to validate prerequisites.
2. Use ./setup help to confirm you are inside the repo root.
3. For Java or Android SDK mismatches, ensure Java 17 is active and the Android SDK/NDK versions match the listed requirements.
4. To recover from Flutter dependency issues, run flutter clean and flutter pub get, or simply re-run ./setup mobile.
5. Emulator issues can often be resolved by ./setup stop-mobile followed by ./setup start-mobile, then inspecting logs/qemu.log if created.

License

Copyright (C) 2025 ExpoScholar contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Contributing

1. Fork the repository and create a topic branch.
2. Follow the established coding standards (PEP 8 for Python, Dart style guidelines with enhanced linting).
3. Run cd mobile && ./tools/analyze_enhanced.sh comprehensive and the relevant Django tests before sending patches.
4. Add or update tests when altering behavior.
5. Provide clear commit messages using the established convention (Overview, Details, Testing, Files, ≤72 chars per line).

Documentation

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

• Info format: View with info exposcholar after building and installing
• HTML format: Single-file HTML manual for web viewing
• PDF format: Printable PDF manual (requires TeX/LaTeX)

Build documentation with:

./setup docs              # Build Info and HTML
make docs                 # Same, using Makefile
./setup docs-pdf          # Build PDF (requires TeX)

The Texinfo source is in docs/exposcholar.texi and organized into modular chapter files under docs/texinfo/chapters/.

Support

• File reproducible issues with environment details and command output.
• Share troubleshooting logs produced by the setup or debug scripts.
• For licensing or collaboration questions, contact the ExpoScholar maintainers via the channels listed in project metadata.

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 while respecting the project’s non-commercial charter. Contributions that reinforce clarity, accuracy, and maintainability are always welcome.