# mizcausevic-dev/advisor-outreach-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/advisor-outreach-orchestrator
- Repository: https://github.com/mizcausevic-dev/advisor-outreach-orchestrator

## Overview

#### Purpose and principal workflow
Advisor Outreach Orchestrator turns student response lag, academic drift, attendance, and support barriers into prioritized outreach recommendations, owner lanes, and channel-specific playbooks. The main workflow starts when an external **HTTP browser or API client** requests a page or API endpoint; the FastAPI application reads the local sample dataset through the outreach service and returns rendered HTML or JSON.

#### Components

##### HTTP interface and presentation
- **HTTP browser or API client** — Path: `null`. External callers request the product’s pages and API endpoints.
- **FastAPI application and routes** — Path: `app/main.py`. Defines the HTTP entry point, serves rendered pages, exposes dashboard, queue, lane, student, and sample endpoints, and returns 404 when a student is not found.
- **Advisor-facing pages** — Path: `app/render.py`. Builds overview, queue, playbook, and API-summary HTML; its rendering functions call the outreach service to obtain page data.

##### Outreach decisioning and source data
- **Outreach scoring and planning** — Path: `app/services/outreach_service.py`. Loads student records, scores urgency, assigns status, channel and owner lane, creates playbook steps, and derives queue, summary, lane, student, and sample-payload views.
- **Sample student dataset** — Path: `app/data/sample_outreach.json`. Supplies the institution, term, and student inputs used by the service; the sampled code shows a file-backed source rather than an external student-system integration.

#### Relationships
- **HTTP browser or API client -> FastAPI application and routes**: sends page or API requests that initiate the workflow.
- **FastAPI application and routes -> Advisor-facing pages**: calls the relevant renderer for HTML page routes.
- **Advisor-facing pages -> Outreach scoring and planning**: reads summaries, queues, playbooks, lane counts, or sample payloads to populate HTML.
- **FastAPI application and routes -> Outreach scoring and planning**: calls service methods for JSON endpoints and student lookup.
- **Outreach scoring and planning -> Sample student dataset**: reads and parses the JSON source when loading records.
- **FastAPI application and routes -> HTTP browser or API client**: returns rendered HTML or endpoint JSON, including a 404 response for an unknown student.

#### Coverage limits
The sampled code establishes a local JSON-backed implementation, but not how production student data would enter or refresh. No outbound messaging, CRM connection, persistence of outreach actions, or asynchronous processing is evidenced.

Main entry points: [`app/main.py`](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/main.py) (FastAPI Routes), [`app/services/outreach_service.py`](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/services/outreach_service.py) (Outreach Planning), [`app/render.py`](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/render.py) (Advisor Pages), [`app/data/sample_outreach.json`](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/data/sample_outreach.json) (Sample Student Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http_presentation["HTTP Interface & Presentation"]
  node_http_client["HTTP Client<br/>External caller"]
  node_fastapi_app["FastAPI Routes<br/>HTTP application"]
  node_advisor_pages["Advisor Pages<br/>HTML renderer"]
end

subgraph group_outreach_decisioning["Outreach Decisioning &amp; Data"]
  node_outreach_service["Outreach Planning<br/>Decision service"]
  node_sample_dataset["Sample Student Dataset<br/>JSON source"]
end

node_http_client -->|"sends requests"| node_fastapi_app
node_fastapi_app -->|"calls renderer"| node_advisor_pages
node_advisor_pages -->|"reads page data"| node_outreach_service
node_fastapi_app -->|"calls service"| node_outreach_service
node_outreach_service -->|"reads JSON"| node_sample_dataset
node_fastapi_app -->|"returns HTML or JSON"| node_http_client

click node_fastapi_app "https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/main.py"
click node_advisor_pages "https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/render.py"
click node_outreach_service "https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/services/outreach_service.py"
click node_sample_dataset "https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/data/sample_outreach.json"

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_http_client,node_fastapi_app,node_advisor_pages toneBlue
class node_outreach_service,node_sample_dataset toneAmber
```

## Components

### HTTP Interface & Presentation

- **HTTP Client**: External caller
- [FastAPI Routes](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/main.py): HTTP application · `app/main.py`
- [Advisor Pages](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/render.py): HTML renderer · `app/render.py`

### Outreach Decisioning & Data

- [Outreach Planning](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/services/outreach_service.py): Decision service · `app/services/outreach_service.py`
- [Sample Student Dataset](https://github.com/mizcausevic-dev/advisor-outreach-orchestrator/blob/main/app/data/sample_outreach.json): JSON source · `app/data/sample_outreach.json`

## Connections

- HTTP Client → FastAPI Routes: sends requests
- FastAPI Routes → Advisor Pages: calls renderer
- Advisor Pages → Outreach Planning: reads page data
- FastAPI Routes → Outreach Planning: calls service
- Outreach Planning → Sample Student Dataset: reads JSON
- FastAPI Routes → HTTP Client: returns HTML or JSON · Includes a 404 response when a student is not found.