# sbalakrishnanbe/multitenant-saas-guidance architecture

> Architecture diagram of the GitHub repository sbalakrishnanbe/multitenant-saas-guidance, 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/sbalakrishnanbe/multitenant-saas-guidance
- Repository: https://github.com/sbalakrishnanbe/multitenant-saas-guidance

## Overview

Tailspin Surveys is a multitenant SaaS survey application, with Azure Active Directory identity management as its central sample concern. Users sign in, then use the web UI to manage or answer surveys; the UI services call a bearer-token API, which authorizes requests and accesses survey data. The tree and excerpts support this outline, including survey, question, tenant, and contributor-request capabilities. Some service-to-API and runtime configuration wiring is not shown, so those links are marked unverified rather than inferred as confirmed calls.

Main entry points: [`src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs) (Survey API), [`src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs`](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs) (Question API), [`src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs`](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs) (Survey store), [`src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs`](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs) (Token service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Survey UI"]
  node_questionui["Question UI"]
  node_homeui["Home UI<br/>[HomeController.cs]"]
  node_surveyservice["Survey service<br/>[SurveyService.cs]"]
  node_questionservice["Question service<br/>[QuestionService.cs]"]
  node_apiresult["API responses<br/>[ApiResult.cs]"]
end

subgraph group_identity["Identity and authorization"]
  node_signin["Sign-in flow"]
  node_signinmanager["Sign-in manager<br/>[SignInManager.cs]"]
  node_tokenservice["Token service"]
  node_tokencache["Token cache"]
  node_policy["Survey policies"]
end

subgraph group_api["Survey API"]
  node_surveyapi["Survey API"]
  node_questionapi["Question API"]
end

subgraph group_data["Survey data"]
  node_surveydata["Survey store"]
  node_questiondata["Question store"]
  node_contributordata["Contributor requests"]
  node_dbcontext["Survey data model"]
  node_surveyentities["Survey entities<br/>[Survey.cs]"]
  node_surveycontracts["Survey DTOs<br/>[SurveyDTO.cs]"]
end

node_user(("User"))
node_aad{{"Azure AD"}}
node_database[("SQL database")]

node_user -->|"manages surveys"| node_webui
node_user -->|"edits questions"| node_questionui
node_user -->|"signs in"| node_signin
node_webui -->|"calls"| node_surveyservice
node_homeui -->|"calls"| node_surveyservice
node_questionui -->|"calls"| node_questionservice
node_surveyservice -.->|"HTTP requests"| node_surveyapi
node_questionservice -.->|"HTTP requests"| node_questionapi
node_signin -->|"delegates sign-out"| node_signinmanager
node_signinmanager -->|"uses tokens"| node_tokenservice
node_tokenservice -->|"uses cache"| node_tokencache
node_tokenservice -.->|"authenticates with"| node_aad
node_surveyapi -->|"authorizes"| node_policy
node_questionapi -->|"authorizes"| node_policy
node_surveyapi -->|"reads and writes"| node_surveydata
node_surveyapi -->|"processes requests"| node_contributordata
node_questionapi -->|"reads and writes"| node_questiondata
node_questionapi -->|"loads surveys"| node_surveydata
node_surveydata -->|"uses context"| node_dbcontext
node_surveydata -->|"persists"| node_surveyentities
node_dbcontext -.->|"stores entities"| node_database
node_surveyapi -->|"maps payloads"| node_surveycontracts

click node_webui "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/SurveyController.cs"
click node_questionui "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/QuestionController.cs"
click node_homeui "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/HomeController.cs"
click node_surveyservice "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Services/SurveyService.cs"
click node_questionservice "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Services/QuestionService.cs"
click node_apiresult "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Models/ApiResult.cs"
click node_signin "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/AccountController.cs"
click node_signinmanager "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Security/SignInManager.cs"
click node_tokenservice "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs"
click node_tokencache "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.TokenStorage/DistributedTokenCacheService.cs"
click node_policy "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Security/Policy/SurveyAuthorizationHandler.cs"
click node_surveyapi "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs"
click node_questionapi "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs"
click node_surveydata "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs"
click node_questiondata "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerQuestionStore.cs"
click node_contributordata "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerContributorRequestStore.cs"
click node_dbcontext "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataModels/ApplicationDbContext.cs"
click node_surveyentities "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataModels/Survey.cs"
click node_surveycontracts "https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DTOs/SurveyDTO.cs"

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_webui,node_questionui,node_homeui,node_surveyservice,node_questionservice,node_apiresult,node_user toneBlue
class node_signin,node_signinmanager,node_tokenservice,node_tokencache,node_policy,node_database toneAmber
class node_surveyapi,node_questionapi toneMint
class node_surveydata,node_questiondata,node_contributordata,node_dbcontext,node_surveyentities,node_surveycontracts toneRose
class node_aad toneIndigo
```

## Components

### Web experience

- [Survey UI](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/SurveyController.cs): `src/Tailspin.Surveys.Web/Controllers/SurveyController.cs`
- [Question UI](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/QuestionController.cs): `src/Tailspin.Surveys.Web/Controllers/QuestionController.cs`
- [Home UI](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/HomeController.cs): `src/Tailspin.Surveys.Web/Controllers/HomeController.cs`
- [Survey service](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Services/SurveyService.cs): `src/Tailspin.Surveys.Web/Services/SurveyService.cs`
- [Question service](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Services/QuestionService.cs): `src/Tailspin.Surveys.Web/Services/QuestionService.cs`
- [API responses](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Models/ApiResult.cs): `src/Tailspin.Surveys.Web/Models/ApiResult.cs`

### Identity and authorization

- [Sign-in flow](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Controllers/AccountController.cs): `src/Tailspin.Surveys.Web/Controllers/AccountController.cs`
- [Sign-in manager](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Security/SignInManager.cs): `src/Tailspin.Surveys.Web/Security/SignInManager.cs`
- [Token service](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs): `src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs`
- [Token cache](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.TokenStorage/DistributedTokenCacheService.cs): `src/Tailspin.Surveys.TokenStorage/DistributedTokenCacheService.cs`
- [Survey policies](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Security/Policy/SurveyAuthorizationHandler.cs): `src/Tailspin.Surveys.Security/Policy/SurveyAuthorizationHandler.cs`

### Survey API

- [Survey API](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs): `src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`
- [Question API](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs): `src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs`

### Survey data

- [Survey store](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs): `src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs`
- [Question store](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerQuestionStore.cs): `src/Tailspin.Surveys.Data/DataStore/SqlServerQuestionStore.cs`
- [Contributor requests](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataStore/SqlServerContributorRequestStore.cs): `src/Tailspin.Surveys.Data/DataStore/SqlServerContributorRequestStore.cs`
- [Survey data model](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataModels/ApplicationDbContext.cs): `src/Tailspin.Surveys.Data/DataModels/ApplicationDbContext.cs`
- [Survey entities](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DataModels/Survey.cs): `src/Tailspin.Surveys.Data/DataModels/Survey.cs`
- [Survey DTOs](https://github.com/sbalakrishnanbe/multitenant-saas-guidance/blob/master/src/Tailspin.Surveys.Data/DTOs/SurveyDTO.cs): `src/Tailspin.Surveys.Data/DTOs/SurveyDTO.cs`

### Other components

- **User**
- **Azure AD**
- **SQL database**

## Connections

- User → Survey UI: manages surveys (evidence: `src/Tailspin.Surveys.Web/Controllers/SurveyController.cs`)
- User → Question UI: edits questions (evidence: `src/Tailspin.Surveys.Web/Controllers/QuestionController.cs`)
- User → Sign-in flow: signs in (evidence: `src/Tailspin.Surveys.Web/Controllers/AccountController.cs`)
- Survey UI → Survey service: calls (evidence: `src/Tailspin.Surveys.Web/Controllers/SurveyController.cs`)
- Home UI → Survey service: calls (evidence: `src/Tailspin.Surveys.Web/Controllers/HomeController.cs`)
- Question UI → Question service: calls (evidence: `src/Tailspin.Surveys.Web/Controllers/QuestionController.cs`)
- Survey service → Survey API: HTTP requests
- Question service → Question API: HTTP requests
- Sign-in flow → Sign-in manager: delegates sign-out (evidence: `src/Tailspin.Surveys.Web/Controllers/AccountController.cs`)
- Sign-in manager → Token service: uses tokens (evidence: `src/Tailspin.Surveys.Web/Security/SignInManager.cs`)
- Token service → Token cache: uses cache (evidence: `src/Tailspin.Surveys.Web/Security/SurveysTokenService.cs`)
- Token service → Azure AD: authenticates with (evidence: `README.md`)
- Survey API → Survey policies: authorizes (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`)
- Question API → Survey policies: authorizes (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs`)
- Survey API → Survey store: reads and writes (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`)
- Survey API → Contributor requests: processes requests (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`)
- Question API → Question store: reads and writes (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs`)
- Question API → Survey store: loads surveys (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/QuestionController.cs`)
- Survey store → Survey data model: uses context (evidence: `src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs`)
- Survey store → Survey entities: persists (evidence: `src/Tailspin.Surveys.Data/DataStore/SqlServerSurveyStore.cs`)
- Survey data model → SQL database: stores entities
- Survey API → Survey DTOs: maps payloads (evidence: `src/Tailspin.Surveys.WebAPI/Controllers/SurveyController.cs`)
