# tjcsl/ion architecture

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

- Interactive diagram: https://gitdiagram.com/tjcsl/ion
- Repository: https://github.com/tjcsl/ion

## Overview

Ion is TJHSST’s Django intranet for students, teachers, and staff. The principal workflow is: a user reaches the web application, authenticates, selects an intranet capability, and receives student information, announcements, events, or Eighth Period signup results. Distinct stages include access control, domain operations, persistence, and asynchronous notification/integration work. The tree and sampled sources strongly support Eighth tasks, event imports, emergency status caching, email, and websocket routing; other app branches are represented from documented capabilities and paths without asserting unsampled calls.

Main entry points: [`intranet/urls.py`](https://github.com/tjcsl/ion/blob/dev/intranet/urls.py) (Django Web App), [`intranet/celery.py`](https://github.com/tjcsl/ion/blob/dev/intranet/celery.py) (Background Tasks), [`intranet/apps/eighth`](https://github.com/tjcsl/ion/tree/dev/intranet/apps/eighth) (Eighth Signup), [`intranet/apps/events`](https://github.com/tjcsl/ion/tree/dev/intranet/apps/events) (School Events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Core"]
  node_web["Django Web App<br/>[urls.py]"]
  node_auth["Authentication"]
  node_users["User Profiles"]
  node_dashboard["Dashboard"]
end

subgraph group_student["Student Services"]
  node_announcements["Announcements"]
  node_events["School Events"]
  node_search["Site Search"]
  node_lostfound["Lost and Found"]
end

subgraph group_eighth["Eighth Program"]
  node_eighth_app["Eighth Signup"]
  node_eighth_data[("Eighth Data<br/>[models.py]")]
  node_groups["Student Groups"]
end

subgraph group_realtime["Realtime and Messaging"]
  node_notifications["Notification Tasks"]
  node_bus["Bus Tracking"]
  node_signage["Digital Signage"]
end

subgraph group_ops["Operations and Integrations"]
  node_celery["Background Tasks<br/>[celery.py]"]
  node_dataimport["Data Imports"]
  node_emergency["Emergency Status"]
end

node_user(("School User"))
node_postgres[("Postgres Database")]
node_redis[("Redis Cache")]
node_sports["Sports Website"]
node_status_services["Status Services"]
node_email["Email Service"]

node_user -->|"opens intranet"| node_web
node_web -->|"dispatches auth"| node_auth
node_auth -->|"resolves users"| node_users
node_web -->|"dispatches dashboard"| node_dashboard
node_web -->|"dispatches announcements"| node_announcements
node_web -->|"dispatches events"| node_events
node_web -->|"dispatches search"| node_search
node_web -->|"dispatches signup"| node_eighth_app
node_eighth_app -->|"reads and writes"| node_eighth_data
node_eighth_app -->|"uses groups"| node_groups
node_eighth_app -->|"queues work"| node_celery
node_celery -->|"runs notifications"| node_notifications
node_notifications -->|"sends email"| node_email
node_web -->|"dispatches bus"| node_bus
node_web -->|"dispatches signage"| node_signage
node_bus -->|"reads routes"| node_postgres
node_signage -->|"reads displays"| node_postgres
node_celery -->|"runs imports"| node_events
node_events -.->|"fetches schedules"| node_sports
node_events -->|"stores events"| node_postgres
node_celery -->|"runs updates"| node_emergency
node_emergency -.->|"fetches status"| node_status_services
node_emergency -->|"writes cache"| node_redis
node_celery -->|"runs imports"| node_dataimport
node_dataimport -->|"writes records"| node_postgres
node_celery -->|"expires items"| node_lostfound
node_lostfound -->|"updates items"| node_postgres

click node_web "https://github.com/tjcsl/ion/blob/dev/intranet/urls.py"
click node_auth "https://github.com/tjcsl/ion/tree/dev/intranet/apps/auth"
click node_users "https://github.com/tjcsl/ion/tree/dev/intranet/apps/users"
click node_dashboard "https://github.com/tjcsl/ion/tree/dev/intranet/apps/dashboard"
click node_announcements "https://github.com/tjcsl/ion/tree/dev/intranet/apps/announcements"
click node_events "https://github.com/tjcsl/ion/tree/dev/intranet/apps/events"
click node_search "https://github.com/tjcsl/ion/tree/dev/intranet/apps/search"
click node_eighth_app "https://github.com/tjcsl/ion/tree/dev/intranet/apps/eighth"
click node_eighth_data "https://github.com/tjcsl/ion/blob/dev/intranet/apps/eighth/models.py"
click node_groups "https://github.com/tjcsl/ion/tree/dev/intranet/apps/groups"
click node_notifications "https://github.com/tjcsl/ion/tree/dev/intranet/apps/notifications"
click node_bus "https://github.com/tjcsl/ion/tree/dev/intranet/apps/bus"
click node_signage "https://github.com/tjcsl/ion/tree/dev/intranet/apps/signage"
click node_celery "https://github.com/tjcsl/ion/blob/dev/intranet/celery.py"
click node_dataimport "https://github.com/tjcsl/ion/tree/dev/intranet/apps/dataimport"
click node_emergency "https://github.com/tjcsl/ion/tree/dev/intranet/apps/emerg"
click node_lostfound "https://github.com/tjcsl/ion/tree/dev/intranet/apps/lostfound"

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_web,node_auth,node_users,node_dashboard,node_user toneBlue
class node_announcements,node_events,node_search,node_lostfound,node_postgres,node_redis toneAmber
class node_eighth_app,node_eighth_data,node_groups toneMint
class node_notifications,node_bus,node_signage toneRose
class node_celery,node_dataimport,node_emergency,node_sports,node_status_services,node_email toneIndigo
```

## Components

### Access and Core

- [Django Web App](https://github.com/tjcsl/ion/blob/dev/intranet/urls.py): `intranet/urls.py`
- [Authentication](https://github.com/tjcsl/ion/tree/dev/intranet/apps/auth): `intranet/apps/auth`
- [User Profiles](https://github.com/tjcsl/ion/tree/dev/intranet/apps/users): `intranet/apps/users`
- [Dashboard](https://github.com/tjcsl/ion/tree/dev/intranet/apps/dashboard): `intranet/apps/dashboard`

### Student Services

- [Announcements](https://github.com/tjcsl/ion/tree/dev/intranet/apps/announcements): `intranet/apps/announcements`
- [School Events](https://github.com/tjcsl/ion/tree/dev/intranet/apps/events): `intranet/apps/events`
- [Site Search](https://github.com/tjcsl/ion/tree/dev/intranet/apps/search): `intranet/apps/search`
- [Lost and Found](https://github.com/tjcsl/ion/tree/dev/intranet/apps/lostfound): `intranet/apps/lostfound`

### Eighth Program

- [Eighth Signup](https://github.com/tjcsl/ion/tree/dev/intranet/apps/eighth): `intranet/apps/eighth`
- [Eighth Data](https://github.com/tjcsl/ion/blob/dev/intranet/apps/eighth/models.py): `intranet/apps/eighth/models.py`
- [Student Groups](https://github.com/tjcsl/ion/tree/dev/intranet/apps/groups): `intranet/apps/groups`

### Realtime and Messaging

- [Notification Tasks](https://github.com/tjcsl/ion/tree/dev/intranet/apps/notifications): `intranet/apps/notifications`
- [Bus Tracking](https://github.com/tjcsl/ion/tree/dev/intranet/apps/bus): `intranet/apps/bus`
- [Digital Signage](https://github.com/tjcsl/ion/tree/dev/intranet/apps/signage): `intranet/apps/signage`

### Operations and Integrations

- [Background Tasks](https://github.com/tjcsl/ion/blob/dev/intranet/celery.py): `intranet/celery.py`
- [Data Imports](https://github.com/tjcsl/ion/tree/dev/intranet/apps/dataimport): `intranet/apps/dataimport`
- [Emergency Status](https://github.com/tjcsl/ion/tree/dev/intranet/apps/emerg): `intranet/apps/emerg`

### Other components

- **School User**
- **Postgres Database**
- **Redis Cache**
- **Sports Website**
- **Status Services**
- **Email Service**

## Connections

- School User → Django Web App: opens intranet
- Django Web App → Authentication: dispatches auth
- Authentication → User Profiles: resolves users
- Django Web App → Dashboard: dispatches dashboard
- Django Web App → Announcements: dispatches announcements
- Django Web App → School Events: dispatches events
- Django Web App → Site Search: dispatches search
- Django Web App → Eighth Signup: dispatches signup
- Eighth Signup → Eighth Data: reads and writes
- Eighth Signup → Student Groups: uses groups
- Eighth Signup → Background Tasks: queues work
- Background Tasks → Notification Tasks: runs notifications
- Notification Tasks → Email Service: sends email
- Django Web App → Bus Tracking: dispatches bus
- Django Web App → Digital Signage: dispatches signage
- Bus Tracking → Postgres Database: reads routes
- Digital Signage → Postgres Database: reads displays
- Background Tasks → School Events: runs imports
- School Events → Sports Website: fetches schedules
- School Events → Postgres Database: stores events
- Background Tasks → Emergency Status: runs updates
- Emergency Status → Status Services: fetches status
- Emergency Status → Redis Cache: writes cache
- Background Tasks → Data Imports: runs imports
- Data Imports → Postgres Database: writes records
- Background Tasks → Lost and Found: expires items
- Lost and Found → Postgres Database: updates items
