Enterprise Operations Portal

Executive summary

This case study documents a private enterprise operations portal developed from a help-desk foundation and expanded into a modular internal platform.

The system began with HESK-based support workflows. Over time, the organization needed the same authenticated environment to handle additional operational domains: asset inventory, maintenance requests, marketing work, vehicle and travel scheduling, service orders, dashboards, and integrations with internal infrastructure services.

A complete rewrite would have delayed useful improvements and increased migration risk. The chosen strategy was incremental modernization: preserve the proven ticketing core, create explicit module boundaries, centralize shared concerns, and introduce APIs, migrations, automated deployment, and observability where they produced concrete operational value.

A later device and asset integration became an important validation of that architecture. The portal could grow from a shared internal interface into a human operational control plane for a distributed integration while keeping external credentials, reconciliation logic, state machines, and privileged mutations inside a separate service boundary. That evolution is documented in detail in Designing a Failure-Safe Device & Asset Integration Control Plane.

The source code, company identity, real addresses, user information, credentials, database names, and topology are intentionally excluded. The architecture and engineering decisions are described at a level that remains technically useful without exposing the operating environment.

Context

The portal supports workflows owned by different departments and used by people with different permissions. Some areas are broadly accessible to authenticated users, while others are limited to specific roles or trusted network locations.

The platform also combines different execution models:

• PHP pages served through Apache;
• HESK sessions and administration conventions;
• JavaScript-enhanced interfaces;
• multiple MySQL databases and schemas;
• Python services for APIs, collectors, and operational integrations;
• persistent attachments and local configuration that must survive deployments;
• scheduled jobs and external service calls;
• a self-hosted deployment runner on the production environment.

The result is not a single isolated application. It is an operational surface connecting people, databases, background services, infrastructure evidence, and business processes.

Problem

As new requirements were added independently, the main risk was fragmentation.

Without a shared architecture, each workflow could have become another disconnected application with its own login, visual language, deployment procedure, permissions, reporting logic, and operational documentation. That would increase support effort and make cross-module improvements harder.

The portal needed to provide:

1. one recognizable entry point;
2. reusable authentication and authorization behavior;
3. clear boundaries between modules;
4. safe evolution of more than one database;
5. controlled access from different network contexts;
6. repeatable deployment and rollback;
7. integrations without exposing database credentials to browsers;
8. dashboards without repeatedly executing expensive aggregation queries;
9. logs and health evidence sufficient for troubleshooting.

Constraints

The implementation had to work within several practical constraints.

Existing production behavior could not be discarded

The ticketing foundation already contained operational history, attachments, users, categories, permissions, and department-specific processes. Replacing it all at once would create more risk than value.

Modules evolved at different speeds

Support, assets, maintenance, marketing, scheduling, and reporting do not share the same release cycle. The architecture had to permit one area to change without requiring a redesign of every other area.

Persistence was not uniform

Some modules extended HESK data. Others used separate schemas or databases. Attachments, generated files, configuration, and cached outputs also had different lifecycle requirements.

Production deployment had to minimize interruption

The PHP layer could usually be updated without restarting Apache. Python services required controlled restarts. Persistent directories could not be replaced blindly by a source checkout.

Internal did not mean unrestricted

Some portal areas could be exposed through more than one network path, but sensitive modules still required tighter server-side controls. Access decisions could not depend only on hidden navigation links.

Sanitized architecture

The following diagram intentionally omits real hosts, addresses, database names, credentials, and network boundaries.

The architecture treats the PHP portal as the interaction layer, not as the only execution environment. Background collection and integration tasks are delegated to Python services where a long-running process or API boundary is more appropriate.

The later device and asset project reinforced this boundary rather than weakening it. The portal gained richer operational workflows, but the system that owns correlation, reconciliation, audit state, external adapters, and write safety remains independently deployable behind an authenticated API.

Modules

The public description groups the private modules into functional categories rather than exposing internal names.

Support and request management

The original ticketing workflow remains the operational foundation. Categories, assignment, status, history, attachments, and user communication are retained while the surrounding portal provides a broader navigation and integration layer.

Knowledge base and AI-assisted authoring

The original HESK knowledge base used HTML as its main authoring and storage format. That path remains available for all legacy articles, avoiding a mandatory collection-wide conversion and the risk of unexpected changes to already published content.

New articles can use Markdown as their canonical source. A shared pipeline applies CommonMark/GFM, HTML sanitization, code highlighting, and preparation of Mermaid diagrams served from local assets. The administrative editor uses server-side preview, and the published view shares the same typography rules, reducing differences between authoring and reading.

A dedicated contract also exposes the format and canonical source to the knowledge-base connector. AI agents can retrieve the original Markdown, prepare drafts, and append sections with hash-based concurrency control, while authentication, permissions, publication state, and human review remain Portal responsibilities. The complete architecture is documented in Modernizing a Legacy Knowledge Base with Markdown, Mermaid, and AI.

Asset management

The asset area originally focused on structured inventory and relationships between computers, components, users or responsible parties, departments, monitors, printers, and compatibility rules.

It later evolved into an operational surface that can also present technical device identity, patrimonial linkage, current possession, newly discovered asset candidates, reassociation after reimage, offboarding state, and lifecycle observations. The portal does not declare all of those facts authoritative itself. It presents the current state and the actions allowed by the integration domain, while the underlying systems retain explicit ownership of identity, physical assets, and checkout state.

The deeper authority and reconciliation model is covered separately in Designing a Failure-Safe Device & Asset Integration Control Plane.

Departmental service workflows

Dedicated modules support areas such as maintenance, marketing, general services, and service orders. Each module applies its own required fields and permissions while reusing the shared application shell.

Scheduling and reservations

Reservation and travel-related workflows introduce date-based validation, availability, and operational planning. These processes require different rules from ticket management but benefit from the same authenticated portal.

Dashboards and reporting

Operational dashboards consolidate ticket statistics, departmental workload, backup state, remote-access events, and other infrastructure evidence. They are designed to summarize source systems rather than become the authoritative source for those systems.

Authentication and authorization

The portal reuses established HESK authentication and session behavior where appropriate, then adds explicit permission checks for custom modules and actions.

Authorization is applied at multiple levels:

• whether a module appears in navigation;
• whether its route can be accessed directly;
• whether the current administrator or user has the required capability;
• whether a create, update, delete, export, or administrative action is permitted;
• whether the request originates from an approved network context when the module requires it.

Network-aware exposure is a secondary control, not a replacement for identity and permission checks. A hidden menu item or an internal IP address alone is not treated as authorization.

Multi-database strategy

The platform does not force every operational domain into one database.

This decision reflects the way the system evolved: some modules extend the help-desk data model, while others own distinct entities and release cycles. A shared bootstrap and configuration layer resolves the appropriate connection for each module.

The main principles are:

• a module should own the tables it changes;
• cross-module reads should be explicit;
• business transactions should avoid depending on distributed writes across databases;
• reporting may aggregate from multiple sources, but the source systems remain authoritative;
• credentials and environment-specific connection values remain outside the public repository and outside browser-delivered code.

The tradeoff is additional operational discipline. Schema versions, backup coverage, deployment order, and rollback procedures must account for more than one persistence boundary.

Migrations and rollback

Database changes are versioned alongside the module that requires them. Production changes are not expected to be applied through undocumented manual edits.

The deployment process distinguishes three concerns:

1. application files that may be replaced from version control;
2. persistent files that must be preserved;
3. schema changes that require an explicit migration step.

For HESK upgrades, the process also separates the vendor updater from custom structural changes. The target schema is validated after the official upgrade, and only the required structural delta is applied to custom tables or fields.

Rollback is planned before deployment. Depending on the change, it may include:

• redeploying the previous application revision;
• restoring preserved configuration or generated assets;
• reversing a migration when a safe down operation exists;
• restoring a database backup when reversal would be ambiguous or destructive;
• restarting the affected Python service without restarting unrelated web components.

Not every database change is safely reversible. The runbook therefore treats backup and restore capability as part of migration design rather than as an afterthought.

Integrations and APIs

Python and FastAPI provide a boundary for tasks that should not be implemented as synchronous PHP page logic.

Examples include:

• collecting or normalizing operational events;
• exposing internal metrics to dashboards;
• reading generated backup or inventory evidence;
• receiving authenticated events from infrastructure systems;
• providing stable data contracts to multiple portal views;
• performing scheduled aggregation outside an interactive request.

These services use narrow endpoints and dedicated authentication mechanisms. They do not expose arbitrary database access or client-selected filesystem paths.

The portal consumes the results and formats them for users, while each integration remains responsible for its own collection and validation logic.

From internal portal to operational control plane

The device and asset integration made this separation concrete. Instead of teaching the browser-facing PHP layer how to authenticate to every external platform and reproduce their business rules, the Portal became the place where an operator sees state, understands blockers, reviews a preview, and explicitly confirms an operation.

The responsibility chain is intentionally directional:

Operator
    ↓
Enterprise Operations Portal
    ↓
Read state / preview / explicit confirmation
    ↓
Authenticated integration API
    ↓
Domain state + reconciliation + audit
    ↓
External systems through server-side adapters

The browser never receives privileged Microsoft Graph or asset-management credentials. It also does not independently decide whether a mutation is safe. The service performs structural and live preflight checks, applies idempotency and rollout gates, persists operation evidence, and returns blockers or terminal state to the Portal.

This also changed the UI contract. Missing backend data is represented as unavailable, not silently converted into a false negative such as “no checkout” or “no issue”. Potentially mutating workflows are preview-first, and ambiguous states are surfaced for human review rather than resolved through client-side heuristics.

That design allows the Portal to become more operationally powerful without becoming the privileged integration engine itself.

Deployment model

Changes are delivered through GitHub Actions to a self-hosted runner in the production environment.

The deployment workflow is intentionally selective:

• source-controlled application files are updated from the approved branch;
• persistent attachments and local configuration are preserved;
• dependency handling is performed only where required;
• database migrations are executed as explicit deployment steps;
• the Python backend is restarted in a controlled manner;
• Apache is left running when the PHP update does not require a restart;
• deployment logs provide evidence of the revision and operations applied.

This replaced an error-prone model based on editing production files directly and manually remembering which services needed attention.

Observability

The platform records evidence at several layers:

• PHP and web-server errors;
• Python service logs;
• integration-specific logs;
• deployment output;
• task and service status;
• generated operational reports;
• dashboard data freshness;
• health endpoints for supporting services.

Expensive reporting queries can be isolated behind cached or precomputed outputs. The cache is treated as disposable: it can be regenerated from authoritative sources and is not used as the only record of an operational event.

For control-plane workflows, observability also includes the distinction between Portal presentation state and integration operation state. The UI can show that an operation is pending, blocked, waiting for external convergence, or complete without having to duplicate the state machine in PHP.

This distinction prevents a dashboard optimization from becoming an accidental data store and prevents the UI from becoming an accidental workflow engine.

Security decisions

The system applies defense in depth within the limits of an incremental modernization project.

Key decisions include:

• reusing authenticated sessions instead of creating parallel identity silos;
• enforcing permissions on routes and actions, not only in navigation;
• limiting selected modules by network context in addition to role checks;
• storing secrets and production-specific configuration outside version control;
• separating browser-facing PHP from service credentials and collectors;
• keeping privileged external adapters and credentials behind authenticated server-side API boundaries;
• requiring preview, explicit confirmation, and server-side preflight for higher-impact integration workflows;
• representing unavailable or ambiguous integration evidence explicitly instead of inferring a safe state in the UI;
• protecting persistent files during deployment;
• restricting integrations to explicit contracts;
• retaining logs without writing credentials or tokens into them;
• sanitizing screenshots, exports, and documentation before external publication;
• keeping the private source and real topology unpublished.

The system is internal, but internal traffic and authenticated users are not assumed to be automatically authorized for every operation.

Results

The project produced qualitative operational improvements without requiring a disruptive rewrite.

A single operational entry point

Users can reach multiple workflows through a consistent portal instead of learning unrelated applications and addresses.

Reusable controls

Authentication, permissions, navigation, shared assets, configuration loading, logging conventions, and deployment behavior are reused across modules.

Independent evolution

New modules can be added or changed without forcing every existing workflow into the same schema or release cycle.

A knowledge base ready for people and agents

The Portal preserved every existing HTML article and introduced Markdown as the canonical format for new content. Technical procedures can now include code, tables, and Mermaid diagrams in a readable and reusable source without changing the browser-delivered format.

The connector receives an explicitly typed representation suitable for automated reading and authoring. Drafts, sanitization, permissions, and content hashes keep automation within verifiable operational boundaries. The details and trade-offs of this evolution are covered in Modernizing a Legacy Knowledge Base with Markdown, Mermaid, and AI.

A human control plane for distributed integrations

The Portal now provides one controlled surface for inventory, new-asset review, possession, check-in, reassociation, offboarding, lifecycle observations, and operation history while the integration service remains responsible for authority, reconciliation, idempotency, external adapters, and write safety.

This is a concrete example of the original modular strategy working as intended: the UI became substantially more capable without requiring HESK/PHP to absorb the complete distributed-systems domain. The implementation details are covered in Designing a Failure-Safe Device & Asset Integration Control Plane.

Better deployment discipline

Version-controlled delivery, explicit migrations, preserved runtime data, and service-specific restart behavior reduce dependence on manual production edits.

More accessible operational evidence

Dashboards and APIs make logs, statistics, backup state, infrastructure events, reviews, blockers, and integration state easier to inspect while preserving the authority of their source systems.

No performance percentage, cost reduction, ticket-volume improvement, or availability figure is claimed here because those measurements have not been prepared for public release.

Lessons learned

Incremental modernization can be the safer architecture

A rewrite is not automatically cleaner when the existing system contains years of operational behavior. Clear boundaries and controlled replacement can deliver value earlier while reducing migration risk.

Shared infrastructure needs explicit ownership

A common portal shell is useful, but each module still needs ownership of its schema, permissions, integrations, and rollback behavior.

The portal should orchestrate decisions, not absorb every backend responsibility

A useful internal portal can become the place where operators make decisions without becoming the system that directly owns every integration credential, state machine, retry rule, and external write. Moving those responsibilities behind narrow service contracts made the Portal easier to evolve and kept the most failure-sensitive logic independently testable and observable.

Deployment and database design are connected

A schema change is not complete until its deployment order, compatibility window, backup, and recovery path are defined.

Internal systems still need trust boundaries

Network location, authenticated identity, module permissions, and service credentials answer different security questions. None of them should silently substitute for the others.

Observability must identify the authoritative source

Dashboards and caches improve access to information, but they should clearly distinguish fresh source data from derived or delayed summaries.

Limitations

The system still carries constraints inherited from its history.

• Some modules follow HESK conventions that were not designed for a broader application platform.
• Multiple databases increase migration and backup coordination.
• The production stack remains coupled to a Windows-hosted Apache/PHP environment and a self-hosted deployment runner.
• Automated tests do not yet cover every module and integration path.
• Some reporting data may be intentionally delayed by caching or scheduled aggregation.
• The portal is a modular platform, not a fully isolated microservice architecture.

These limitations are documented because hiding them would make the case study less useful and the operational model less safe.

Next steps

The long-term direction is continued separation of concerns rather than a single large rewrite. The device and asset control plane is one concrete example of that direction: the Portal retained the user-facing workflow while a dedicated service took ownership of the distributed integration domain.

Priorities include:

• tracking adoption, review outcomes, and operational quality for new Markdown articles;
• expanding automated tests around permissions, migrations, and API contracts;
• standardizing module-level health and audit events;
• validating schema drift automatically before deployment;
• improving rollback automation and recovery exercises;
• further isolating long-running services from the web frontend;
• centralizing observability without centralizing every operational database;
• continuing to replace legacy coupling when a module has a clear migration path.

Confidentiality statement

This case study intentionally uses a generic identity and sanitized architecture. It contains no restricted HESK customization, proprietary source code, credentials, real hostnames, internal addresses, user records, database names, sensitive metrics, or production topology.