# spt22kousis/ncuacg_net_fork architecture

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

- Interactive diagram: https://gitdiagram.com/spt22kousis/ncuacg_net_fork
- Repository: https://github.com/spt22kousis/ncuacg_net_fork

## Overview

NCU ACG is a club website combining member accounts, club content, attendance, events, and a substantial Songfest management platform. Visitors and members enter through the React application; its pages use the shared API client to reach Django-backed features. Songfest spans submissions, requests, scheduling, and post-event playback records, while attendance can be created from lesson or festival sessions. The README documents these capabilities, but many corresponding views and API modules were not excerpted, so some cross-layer links are intentionally dashed and unverified.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/api/client.ts) (API client), [`NCUACG/NCUACG/settings.py`](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/NCUACG/settings.py) (Django database), [`frontend/src/App.tsx`](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/App.tsx) (React routes), [`NCUACG/songfest/request_views.py`](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/request_views.py) (Songfest endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["React routes<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_identity["Accounts"]
  node_auth_ui["Account pages<br/>[Login.tsx]"]
  node_accounts["Accounts API<br/>[views.py]"]
  node_account_data[("Account records<br/>[models.py]")]
end

subgraph group_club["Club operations"]
  node_club_ui["Club and works<br/>[Works.tsx]"]
  node_club_api["Club content API<br/>[views.py]"]
  node_club_data[("Club content<br/>[models.py]")]
  node_lesson_rules["Lesson notices<br/>[lessons.py]"]
  node_event_api["Event listings<br/>[views.py]"]
  node_checkin_ui["Check-in scanner<br/>[Checkin.tsx]"]
  node_checkin_api["Check-in service<br/>[views.py]"]
  node_checkin_rules["Check-in rules<br/>[rules.py]"]
  node_checkin_data[("Attendance records<br/>[models.py]")]
end

subgraph group_songfest["Songfest"]
  node_songfest_ui["Songfest pages<br/>[Manage.tsx]"]
  node_songfest_api["Songfest endpoints<br/>[request_views.py]"]
  node_submission_rules["Submission rules<br/>[submissions.py]"]
  node_setlist_rules["Setlist engine<br/>[setlist.py]"]
  node_songfest_data[("Songfest records<br/>[models.py]")]
end

subgraph group_assistant["AI assistant"]
  node_chat_ui["Chat widget<br/>[ChatWidget.tsx]"]
  node_chat_hook["Chat hook<br/>[useChat.ts]"]
  node_llm_client["LLM client<br/>[llama_client.py]"]
  node_retriever["Context retriever<br/>[retriever.py]"]
  node_personas["Persona prompts<br/>[personas.py]"]
end

node_visitor(("Visitor / member"))
node_sheets["Google Sheets"]
node_groq{{"Groq model service"}}
node_django_db[("Django database<br/>[settings.py]")]

node_visitor -->|"opens site"| node_webapp
node_webapp -->|"routes to"| node_auth_ui
node_webapp -->|"routes to"| node_club_ui
node_webapp -->|"routes to"| node_songfest_ui
node_auth_ui -.->|"uses API"| node_api_client
node_club_ui -->|"uses API"| node_api_client
node_api_client -.->|"HTTP requests"| node_accounts
node_api_client -.->|"HTTP requests"| node_club_api
node_api_client -.->|"HTTP requests"| node_event_api
node_api_client -.->|"HTTP requests"| node_checkin_api
node_api_client -.->|"HTTP requests"| node_songfest_api
node_accounts -->|"manages"| node_account_data
node_club_api -->|"uses records"| node_club_data
node_lesson_rules -->|"reads lessons"| node_club_data
node_event_api -->|"reads lessons"| node_club_data
node_checkin_api -->|"applies rules"| node_checkin_rules
node_checkin_rules -->|"creates records"| node_checkin_data
node_checkin_ui -.->|"uses API"| node_api_client
node_songfest_ui -.->|"requests features"| node_songfest_api
node_songfest_api -.->|"applies rules"| node_submission_rules
node_songfest_api -.->|"builds schedules"| node_setlist_rules
node_setlist_rules -.->|"uses records"| node_songfest_data
node_submission_rules -.->|"uses records"| node_songfest_data
node_sheets -.->|"imports history"| node_songfest_data
node_chat_ui -->|"uses hook"| node_chat_hook
node_chat_hook -->|"posts messages"| node_api_client
node_llm_client -->|"retrieves context"| node_retriever
node_llm_client -->|"builds prompts"| node_personas
node_llm_client -->|"calls model"| node_groq
node_django_db -.->|"stores"| node_account_data
node_django_db -.->|"stores"| node_club_data
node_django_db -.->|"stores"| node_checkin_data
node_django_db -.->|"stores"| node_songfest_data

click node_webapp "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/api/client.ts"
click node_auth_ui "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/Login.tsx"
click node_accounts "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/accounts/views.py"
click node_account_data "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/accounts/models.py"
click node_club_ui "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/Works.tsx"
click node_club_api "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/views.py"
click node_club_data "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/models.py"
click node_lesson_rules "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/lessons.py"
click node_event_api "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/event/views.py"
click node_checkin_ui "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/club/Checkin.tsx"
click node_checkin_api "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/views.py"
click node_checkin_rules "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/rules.py"
click node_checkin_data "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/models.py"
click node_songfest_ui "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/songfest/Manage.tsx"
click node_songfest_api "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/request_views.py"
click node_submission_rules "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/submissions.py"
click node_setlist_rules "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/setlist.py"
click node_songfest_data "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/models.py"
click node_chat_ui "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/components/ChatWidget.tsx"
click node_chat_hook "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/hooks/useChat.ts"
click node_llm_client "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/llama_client.py"
click node_retriever "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/retriever.py"
click node_personas "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/personas.py"
click node_django_db "https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/NCUACG/settings.py"

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_api_client toneBlue
class node_auth_ui,node_accounts,node_account_data,node_django_db toneAmber
class node_club_ui,node_club_api,node_club_data,node_lesson_rules,node_event_api,node_checkin_ui,node_checkin_api,node_checkin_rules,node_checkin_data toneMint
class node_songfest_ui,node_songfest_api,node_submission_rules,node_setlist_rules,node_songfest_data toneRose
class node_chat_ui,node_chat_hook,node_llm_client,node_retriever,node_personas,node_visitor,node_sheets,node_groq toneIndigo
```

## Components

### Web application

- [React routes](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Accounts

- [Account pages](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/Login.tsx): `frontend/src/pages/Login.tsx`
- [Accounts API](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/accounts/views.py): `NCUACG/accounts/views.py`
- [Account records](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/accounts/models.py): `NCUACG/accounts/models.py`

### Club operations

- [Club and works](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/Works.tsx): `frontend/src/pages/Works.tsx`
- [Club content API](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/views.py): `NCUACG/club/views.py`
- [Club content](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/models.py): `NCUACG/club/models.py`
- [Lesson notices](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/club/lessons.py): `NCUACG/club/lessons.py`
- [Event listings](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/event/views.py): `NCUACG/event/views.py`
- [Check-in scanner](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/club/Checkin.tsx): `frontend/src/pages/club/Checkin.tsx`
- [Check-in service](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/views.py): `NCUACG/checkin/views.py`
- [Check-in rules](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/rules.py): `NCUACG/checkin/rules.py`
- [Attendance records](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/checkin/models.py): `NCUACG/checkin/models.py`

### Songfest

- [Songfest pages](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/pages/songfest/Manage.tsx): `frontend/src/pages/songfest/Manage.tsx`
- [Songfest endpoints](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/request_views.py): `NCUACG/songfest/request_views.py`
- [Submission rules](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/submissions.py): `NCUACG/songfest/submissions.py`
- [Setlist engine](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/setlist.py): `NCUACG/songfest/setlist.py`
- [Songfest records](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/songfest/models.py): `NCUACG/songfest/models.py`

### AI assistant

- [Chat widget](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/components/ChatWidget.tsx): `frontend/src/components/ChatWidget.tsx`
- [Chat hook](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [LLM client](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/llama_client.py): `NCUACG/assistant/services/llama_client.py`
- [Context retriever](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/retriever.py): `NCUACG/assistant/services/retriever.py`
- [Persona prompts](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/assistant/services/personas.py): `NCUACG/assistant/services/personas.py`

### Other components

- **Visitor / member**
- **Google Sheets**
- **Groq model service**
- [Django database](https://github.com/spt22kousis/ncuacg_net_fork/blob/main/NCUACG/NCUACG/settings.py): `NCUACG/NCUACG/settings.py`

## Connections

- Visitor / member → React routes: opens site (evidence: `README.md`)
- React routes → Account pages: routes to (evidence: `frontend/src/App.tsx`)
- React routes → Club and works: routes to (evidence: `frontend/src/App.tsx`)
- React routes → Songfest pages: routes to (evidence: `frontend/src/App.tsx`)
- Account pages → API client: uses API
- Club and works → API client: uses API (evidence: `frontend/src/pages/Works.tsx`)
- API client → Accounts API: HTTP requests
- API client → Club content API: HTTP requests
- API client → Event listings: HTTP requests
- API client → Check-in service: HTTP requests
- API client → Songfest endpoints: HTTP requests
- Accounts API → Account records: manages (evidence: `NCUACG/accounts/views.py`)
- Club content API → Club content: uses records (evidence: `NCUACG/club/models.py`)
- Lesson notices → Club content: reads lessons (evidence: `NCUACG/club/lessons.py`)
- Event listings → Club content: reads lessons (evidence: `NCUACG/event/views.py`)
- Check-in service → Check-in rules: applies rules (evidence: `NCUACG/checkin/views.py`)
- Check-in rules → Attendance records: creates records (evidence: `NCUACG/checkin/rules.py`)
- Check-in scanner → API client: uses API
- Songfest pages → Songfest endpoints: requests features
- Songfest endpoints → Submission rules: applies rules
- Songfest endpoints → Setlist engine: builds schedules
- Setlist engine → Songfest records: uses records
- Submission rules → Songfest records: uses records
- Google Sheets → Songfest records: imports history (evidence: `README.md`)
- Chat widget → Chat hook: uses hook (evidence: `frontend/src/components/ChatWidget.tsx`)
- Chat hook → API client: posts messages (evidence: `frontend/src/hooks/useChat.ts`)
- LLM client → Context retriever: retrieves context (evidence: `NCUACG/assistant/services/llama_client.py`)
- LLM client → Persona prompts: builds prompts (evidence: `NCUACG/assistant/services/llama_client.py`)
- LLM client → Groq model service: calls model (evidence: `NCUACG/assistant/services/llama_client.py`)
- Django database → Account records: stores
- Django database → Club content: stores
- Django database → Attendance records: stores
- Django database → Songfest records: stores