# srihariakula/apexarc2026 architecture

> Architecture diagram of the GitHub repository srihariakula/apexarc2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srihariakula/apexarc2026
- Repository: https://github.com/srihariakula/apexarc2026

## Overview

Von Digitalis Estates is an estate-operations platform for visitor analytics, animal monitoring, ticketing/loyalty, and AI oversight. Its clearest implemented workflow is popularity measurement: gateways or ticket scans submit events, the API stores them, scheduled rollups produce analytics, and staff review recommendations. Animal alerts and population counts follow a separate keeper-review path; visitor identity and ticketing support the customer-facing path. The graph combines sampled server code with README-documented capabilities; cloud MQTT, inference, and production OAuth details are architectural intentions rather than inspected integrations.

Main entry points: [`implementation/server/src/app.js`](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/app.js) (Express API), [`implementation/server/src/db.js`](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/db.js) (PostgreSQL), [`implementation/server/src/services/animal-monitoring/routes.js`](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/animal-monitoring/routes.js) (Animal monitoring), [`implementation/server/src/services/ingestion/routes.js`](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ingestion/routes.js) (Event ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Visitor experience"]
  node_webapp["Web interfaces"]
  node_ticketing["Tickets and loyalty<br/>[routes.js]"]
end

subgraph group_operations["Estate operations"]
  node_ingestion["Event ingestion<br/>[routes.js]"]
  node_animal["Animal monitoring<br/>[routes.js]"]
  node_tiering["Alert tiering<br/>[alertTiering.js]"]
end

subgraph group_intelligence["Analytics and AI"]
  node_popularity["Popularity analytics<br/>[routes.js]"]
  node_aggregation["Hourly and daily rollups<br/>[aggregation.js]"]
  node_recommendations["Forecasts and recommendations<br/>[routes.js]"]
  node_governance["AI governance<br/>[routes.js]"]
end

subgraph group_platform["Application platform"]
  node_identity["Identity and access<br/>[routes.js]"]
  node_auth["Authentication middleware<br/>[auth.js]"]
  node_api["Express API<br/>[app.js]"]
  node_postgres[("PostgreSQL<br/>[db.js]")]
end

node_visitor(("Visitor"))
node_staff(("Keeper and staff"))
node_gateway{{"Sensors and gateways"}}
node_mqtt{{"MQTT and cloud inference"}}
node_oauth{{"OAuth/OIDC provider"}}

node_visitor -->|"uses"| node_webapp
node_staff -->|"uses"| node_webapp
node_webapp -->|"requests APIs"| node_api
node_api -->|"mounts routes"| node_identity
node_api -->|"mounts routes"| node_ticketing
node_api -->|"mounts routes"| node_ingestion
node_api -->|"mounts routes"| node_popularity
node_api -->|"mounts routes"| node_animal
node_api -->|"mounts routes"| node_governance
node_api -->|"attaches user"| node_auth
node_identity -->|"issues tokens"| node_auth
node_auth -->|"loads user and roles"| node_postgres
node_identity -->|"reads and writes accounts"| node_postgres
node_ticketing -->|"stores ticket and loyalty data"| node_postgres
node_ingestion -->|"stores incoming events"| node_postgres
node_gateway -.->|"submits readings"| node_ingestion
node_ingestion -.->|"stands in for MQTT path"| node_mqtt
node_ingestion -.->|"events feed rollups"| node_aggregation
node_popularity -->|"calls rollups"| node_aggregation
node_aggregation -->|"reads and writes aggregates"| node_postgres
node_popularity -->|"reads analytics; records approvals"| node_postgres
node_staff -->|"reviews recommendations"| node_recommendations
node_animal -->|"tiers alert severity"| node_tiering
node_animal -->|"stores alerts and counts"| node_postgres
node_staff -->|"confirms or reviews"| node_animal
node_mqtt -.->|"provides sensor signals"| node_animal
node_animal -.->|"uses vision inference"| node_mqtt
node_governance -->|"records evaluations and promotions"| node_postgres
node_ticketing -->|"reads current popularity"| node_popularity
node_ticketing -.->|"production sign-in"| node_oauth

click node_webapp "https://github.com/srihariakula/apexarc2026/tree/main/implementation/webapp"
click node_ticketing "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ticketing-integration/routes.js"
click node_identity "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/identity-access/routes.js"
click node_auth "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/middleware/auth.js"
click node_api "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/app.js"
click node_ingestion "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ingestion/routes.js"
click node_animal "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/animal-monitoring/routes.js"
click node_tiering "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/animal-monitoring/alertTiering.js"
click node_popularity "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/routes.js"
click node_aggregation "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/aggregation.js"
click node_recommendations "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/routes.js"
click node_governance "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ai-governance/routes.js"
click node_postgres "https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/db.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_ticketing toneBlue
class node_ingestion,node_animal,node_tiering toneAmber
class node_popularity,node_aggregation,node_recommendations,node_governance toneMint
class node_identity,node_auth,node_api,node_postgres toneRose
class node_visitor,node_staff,node_gateway,node_mqtt,node_oauth toneIndigo
```

## Components

### Visitor experience

- [Web interfaces](https://github.com/srihariakula/apexarc2026/tree/main/implementation/webapp): `implementation/webapp`
- [Tickets and loyalty](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ticketing-integration/routes.js): `implementation/server/src/services/ticketing-integration/routes.js`

### Estate operations

- [Event ingestion](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ingestion/routes.js): `implementation/server/src/services/ingestion/routes.js`
- [Animal monitoring](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/animal-monitoring/routes.js): `implementation/server/src/services/animal-monitoring/routes.js`
- [Alert tiering](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/animal-monitoring/alertTiering.js): `implementation/server/src/services/animal-monitoring/alertTiering.js`

### Analytics and AI

- [Popularity analytics](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/routes.js): `implementation/server/src/services/popularity-analytics/routes.js`
- [Hourly and daily rollups](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/aggregation.js): `implementation/server/src/services/popularity-analytics/aggregation.js`
- [Forecasts and recommendations](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/popularity-analytics/routes.js): `implementation/server/src/services/popularity-analytics/routes.js`
- [AI governance](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/ai-governance/routes.js): `implementation/server/src/services/ai-governance/routes.js`

### Application platform

- [Identity and access](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/services/identity-access/routes.js): `implementation/server/src/services/identity-access/routes.js`
- [Authentication middleware](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/middleware/auth.js): `implementation/server/src/middleware/auth.js`
- [Express API](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/app.js): `implementation/server/src/app.js`
- [PostgreSQL](https://github.com/srihariakula/apexarc2026/blob/main/implementation/server/src/db.js): `implementation/server/src/db.js`

### Other components

- **Visitor**
- **Keeper and staff**
- **Sensors and gateways**
- **MQTT and cloud inference**
- **OAuth/OIDC provider**

## Connections

- Visitor → Web interfaces: uses (evidence: `README.md`)
- Keeper and staff → Web interfaces: uses (evidence: `README.md`)
- Web interfaces → Express API: requests APIs (evidence: `implementation/server/src/app.js`)
- Express API → Identity and access: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → Tickets and loyalty: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → Event ingestion: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → Popularity analytics: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → Animal monitoring: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → AI governance: mounts routes (evidence: `implementation/server/src/app.js`)
- Express API → Authentication middleware: attaches user (evidence: `implementation/server/src/app.js`)
- Identity and access → Authentication middleware: issues tokens (evidence: `implementation/server/src/services/identity-access/routes.js`)
- Authentication middleware → PostgreSQL: loads user and roles (evidence: `implementation/server/src/middleware/auth.js`)
- Identity and access → PostgreSQL: reads and writes accounts (evidence: `implementation/server/src/services/identity-access/routes.js`)
- Tickets and loyalty → PostgreSQL: stores ticket and loyalty data (evidence: `implementation/server/src/services/ticketing-integration/routes.js`)
- Event ingestion → PostgreSQL: stores incoming events (evidence: `implementation/server/src/services/ingestion/routes.js`)
- Sensors and gateways → Event ingestion: submits readings (evidence: `implementation/server/src/services/ingestion/routes.js`)
- Event ingestion → MQTT and cloud inference: stands in for MQTT path (evidence: `implementation/server/src/services/ingestion/routes.js`)
- Event ingestion → Hourly and daily rollups: events feed rollups (evidence: `README.md`)
- Popularity analytics → Hourly and daily rollups: calls rollups (evidence: `implementation/server/src/services/popularity-analytics/routes.js`)
- Hourly and daily rollups → PostgreSQL: reads and writes aggregates (evidence: `implementation/server/src/services/popularity-analytics/aggregation.js`)
- Popularity analytics → PostgreSQL: reads analytics; records approvals (evidence: `implementation/server/src/services/popularity-analytics/routes.js`)
- Keeper and staff → Forecasts and recommendations: reviews recommendations (evidence: `README.md`)
- Animal monitoring → Alert tiering: tiers alert severity (evidence: `implementation/server/src/services/animal-monitoring/routes.js`)
- Animal monitoring → PostgreSQL: stores alerts and counts (evidence: `implementation/server/src/services/animal-monitoring/routes.js`)
- Keeper and staff → Animal monitoring: confirms or reviews (evidence: `README.md`)
- MQTT and cloud inference → Animal monitoring: provides sensor signals (evidence: `README.md`)
- Animal monitoring → MQTT and cloud inference: uses vision inference (evidence: `README.md`)
- AI governance → PostgreSQL: records evaluations and promotions (evidence: `implementation/server/src/services/ai-governance/routes.js`)
- Tickets and loyalty → Popularity analytics: reads current popularity (evidence: `implementation/server/src/services/ticketing-integration/routes.js`)
- Tickets and loyalty → OAuth/OIDC provider: production sign-in
