1. System in Plain English
This is a school operations platform that links people, cards, money, school services, and physical access points.
The shortest explanation
ePass lets a school use one identity/account system for access control, POS sales, self-service account recharges, canteen validation, vending, administration, parent/user portals, and cloud synchronization.
What people experience
A student taps a card, buys lunch, enters a gate, uses a vending machine, or has an account recharged. Staff use screens to sell, monitor, approve, and support these activities.
What the system does behind the scenes
It checks rules, updates account balances, records history, sends commands to hardware, shows live activity to staff, and synchronizes with web/cloud components.
2. Big-Picture Architecture
The system has user applications, background services, a database, local kiosk hardware, network access-control hardware, and web/cloud components.
flowchart LR
Users["Students, staff, parents, operators"]
subgraph Apps["User-facing applications"]
Kiosk["POS / kiosk screens"]
Admin["Back-office website"]
Portal["Parent / user portal"]
end
subgraph Services["Background services"]
Core["DSCore: business brain"]
Comm["DSCommServer: hardware translator"]
Sync["Cloud sync worker"]
end
subgraph Data["Memory and history"]
DB[("Local database")]
Cloud["Cloud / web data"]
end
subgraph Hardware["Physical devices"]
Local["Local kiosk devices"]
Network["Readers, gates, vending"]
end
Users --> Apps
Apps --> Core
Kiosk --> Local
Core --> DB
Comm --> Core
Comm --> Network
Sync --> Cloud
3. Main Roles and Analogies
These analogies are intentionally simple so non-technical stakeholders can discuss the system confidently.
DSCore = business brain
Decides whether access is allowed, what sale happened, which user/account is involved, and what should be stored in history.
DSCommServer = translator
Translates between software and physical devices. It helps card readers, gates, and vending controllers communicate with the business system.
Database = memory/history
Stores users, cards, balances, sales, configuration, access records, and audit history.
Windows Service = background worker
A program that runs in the background, even without someone logged in.
COM port = cable/channel
A named communication channel Windows uses to talk to a plugged-in device, such as a card reader or cash acceptor.
Cloud sync = courier
Moves selected information between the local school installation and cloud/web services.
Optional terminology notes
The technical version explains service protocols, device messages, and low-level communication details. This management version keeps the same facts but uses business language: background workers, device translators, communication channels, and system memory/history.
4. Typical School Day Using the Platform
The platform supports several operational moments across a normal day.
Morning entry
Students tap cards at readers. The system checks access rules and records entries.
Office and support work
Staff use back-office screens to manage users, cards, devices, products, and reports.
Canteen and purchases
Students use accounts/cards for meals, POS purchases, or vending activity.
Self-service top-up
A kiosk can accept coins or notes and update the account balance.
Parent/user portal and cloud sync
Web and cloud components support account, authorization, order, and synchronization workflows.
5. Kiosks and Devices
A kiosk is not just a screen. It can be connected to payment devices, card readers, printers, scanners, and cameras.
flowchart TB
Kiosk["POS / self-service kiosk"]
subgraph LocalDevices["Devices attached to the kiosk"]
Card["USB card reader"]
Cash["Coin / note acceptors"]
Printer["Receipt printer"]
Scanner["Barcode scanner"]
Camera["Webcam"]
end
subgraph Services["Background system"]
Core["Business brain"]
Database[("System memory")]
end
Kiosk --> Card
Kiosk --> Cash
Kiosk --> Printer
Kiosk --> Scanner
Kiosk --> Camera
Kiosk --> Core
Core --> Database
Local kiosk hardware
These devices are usually connected to the kiosk machine itself. If the local computer, driver, cable, or port setting changes, the kiosk workflow can fail.
Network access hardware
Readers, gates, and vending controllers are usually reached over the school network through the DSCommServer hardware translator.
6. Key Business Flows
These diagrams keep the technical details hidden and show the business process.
sequenceDiagram
autonumber
participant Student
participant Reader as Card reader
participant System as ePass system
participant DB as System memory
participant Gate as Gate or screen
Student->>Reader: Taps card
Reader->>System: Sends card identity
System->>DB: Checks person, rules, and history
DB-->>System: Returns decision data
System-->>Reader: Allowed or denied
System-->>Gate: Opens gate or updates staff screen
sequenceDiagram
autonumber
participant User
participant Kiosk
participant Cash as Coin/note device
participant System as ePass system
participant DB as System memory
participant Printer
User->>Cash: Inserts coin or note
Cash->>Kiosk: Reports accepted money
Kiosk->>System: Requests account top-up or sale update
System->>DB: Records transaction
DB-->>System: Confirms record
System-->>Kiosk: Shows updated result
Kiosk->>Printer: Prints receipt if configured
sequenceDiagram
autonumber
participant Person
participant Reader
participant Core as Business brain
participant Translator as Hardware translator
participant Gate
Person->>Reader: Presents card
Reader->>Core: Access request
Core-->>Translator: Open gate if allowed
Translator-->>Gate: Physical open command
7. What Happens When Something Breaks
Hardware systems are harder to diagnose because a failure can be physical, configuration-related, network-related, service-related, or business-rule related.
| Symptom | Possible business impact | Why diagnosis can be difficult |
|---|---|---|
| Card does not open a gate | Students/staff cannot enter normally; support must intervene. | Could be card, reader, network, DSCommServer, DSCore, database rules, or gate controller. |
| Kiosk does not accept money | Users cannot recharge accounts; manual support workload increases. | Could be cash device state, COM port setting, cable, driver, kiosk timer, or POS process. |
| Receipt does not print | Payment confidence and support evidence are reduced. | Could be printer driver, Windows printer queue, wrong printer setting, or POS print flow. |
| Live gate screen stops updating | Staff lose real-time visibility. | Could be service callback, network, POS subscription, DSCore, or application state. |
8. Why Hardware Systems Are Special
A normal website mostly deals with screens and databases. This system also depends on real devices.
Physical world
Cables, power, drivers, ports, and device firmware all affect software behavior.
Timing matters
Devices expect quick responses. A missed acknowledgement can stop a payment or access flow.
Local variation
Each kiosk may have different ports, printers, readers, or hardware settings.
Operational pressure
Failures affect queues, entry gates, payments, and staff workload immediately.
Older technology
The stack is legacy but business-critical, so changes must be controlled and tested.
Many moving parts
A single card tap can involve a reader, background services, rules, database records, and a physical gate.
9. Why This System Is Hard to Replace
The difficulty is not just rewriting screens. The system embeds years of device behavior, operational rules, deployment assumptions, and school-specific workflows.
Hidden operational knowledge
Device protocols, installer behavior, firewall settings, printer names, COM ports, and host configuration are part of the real system even if they are not obvious from UI screens.
Real-world failure cost
A replacement that looks good in a demo can still fail in production if it does not handle device timing, reconnects, payment acknowledgement, and gate control correctly.
10. Business Risks
These risks should guide investment, support planning, and modernization sequencing.
Legacy .NET platform
Older technology can increase maintenance cost, hiring difficulty, security review effort, and upgrade complexity.
Hardware dependency
Operational success depends on devices, drivers, cables, ports, IP addresses, and local machine setup.
Limited observability
Without a clear health dashboard, support may spend too much time finding where a failure happened.
Fragile field configuration
A small configuration change can stop a kiosk, reader, printer, gate, or payment device from working.
Older background processing model
Some long-running background code uses older patterns that can make recovery and restart behavior less predictable.
Replacement risk
A full rewrite would need to reproduce both business rules and physical device behavior at the same time.
11. Good News
The codebase is legacy, but it has important architectural strengths that should be preserved.
The business brain and hardware translator are separated
DSCore handles rules and records. DSCommServer handles network hardware. This is the right high-level boundary.
Logging already exists
Existing logging provides a foundation for better health checks, dashboards, and support workflows.
Emulators exist
A card reader emulator exists, which is valuable for development, training, and testing without physical devices.
Modernization can be incremental
The system does not need to be rewritten first. It can be stabilized, observed, wrapped, and modernized in phases.
12. What Modernization Should Look Like
The safest modernization path is staged. The first goal should be visibility and stability, not a big-bang replacement.
flowchart LR
subgraph Current["Current"]
OldUI["WPF kiosk/POS"]
OldServices["Legacy background services"]
OldHardware["Device code mixed into services/UI"]
end
subgraph Future["Future"]
NewUI["Replaceable web/Electron or improved UI"]
API["Modern local/API layer"]
Adapters["Hardware adapters"]
Health["Device health dashboard"]
end
OldUI --> API
OldServices --> API
OldHardware --> Adapters
API --> Health
flowchart LR
A["1. Document current runtime"]
B["2. Build diagnostics tool"]
C["3. Improve logs and health checks"]
D["4. Add hardware interfaces"]
E["5. Add modern API facade"]
F["6. Modernize UI/runtime"]
A --> B --> C --> D --> E --> F
Document current runtime
Know exactly what is installed, which ports are used, and which devices are configured.
Build diagnostics tool
Reduce time spent guessing whether a problem is hardware, service, configuration, or business rules.
Improve logs and health checks
Give support a live view of service/device status and recent failures.
Introduce hardware interfaces
Create safer boundaries so future UI or service changes do not directly disturb device behavior.
Add modern API facade
Allow new applications to use stable APIs while the old system continues to run underneath.
Modernize UI/runtime last
Replace or upgrade screens and services after the device and API boundaries are safer.
13. Why a Diagnostics Tool Would Reduce Operational Costs
A diagnostics tool turns field support from guesswork into a guided checklist.
Faster triage
Support can quickly see whether a device is connected, which port/IP it uses, and when it last responded.
Lower travel and escalation
Many problems can be diagnosed remotely before sending hardware specialists on site.
Safer releases
Teams can test readers, cash devices, gates, and printers before and after upgrades.
Better accountability
It becomes clearer whether a problem is software, hardware, network, configuration, or business rules.
Training value
New support staff can learn system behavior without needing a full live school deployment.
Modernization foundation
Diagnostics provide the visibility needed before changing legacy services or replacing the UI.
14. Confirmed Findings vs Assumptions
This page avoids unsupported claims. Some physical details cannot be proven from source code alone.
Confirmed from the codebase
- The platform includes POS/kiosk, backend services, web portals, API, cloud sync, and hardware communication code.
- DSCore is the business service host.
- DSCommServer handles network hardware communication.
- POS controls local kiosk devices such as card readers, cash devices, printers, scanners, and webcams.
- The system uses legacy .NET Framework technologies.
Assumptions or uncertain details
- Exact device brands/models are not fully identified in the repository.
- Turnstile support is inferred from gate/door access-control behavior.
- Some optional integrations, such as Cashlogy, may not be active in every deployment.
- Deployment topology may vary by school/customer installation.
15. One-Page Executive Summary
A concise summary for directors, project managers, and stakeholders.
What this system is
ePass is a school campus system for card identity, access control, POS sales, self-service account recharges, canteen validation, vending, administration, portals, and cloud synchronization.
What works in its favor
The most important separation already exists: DSCore handles business decisions, and DSCommServer handles network hardware. Logging and emulators also give the team a foundation for better operations and testing.
Why it needs careful management
It is a legacy system that controls real devices. Modernization must account for hardware timing, drivers, field configuration, service startup, database rules, and operational continuity.
Recommended action
Do not start with a rewrite. First document the live runtime, build a diagnostics tool, improve health checks, introduce hardware boundaries, add a modern API layer, and then modernize the UI and runtime in phases.