# qosam217/inst-sons architecture

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

- Interactive diagram: https://gitdiagram.com/qosam217/inst-sons
- Repository: https://github.com/qosam217/inst-sons

## Overview

Inst Sons is a web utility suite whose main workflow is an authenticated user selecting a tool, submitting a file or YouTube URL, and receiving a processed download; audio and YouTube jobs additionally expose status polling. The frontend pages and services connect users to the Express API, whose modular routes dispatch to controllers and domain services. PDF and image processing are documented as buffer-based where applicable; audio tasks use temporary files. README capabilities guide unsampled subsystem coverage; detailed service and frontend-page wiring was not inspected, so those links are shown only at documented API boundaries.

Main entry points: [`backend/server.js`](https://github.com/qosam217/inst-sons/blob/main/backend/server.js) (Express server), [`frontend/src/app`](https://github.com/qosam217/inst-sons/tree/main/frontend/src/app) (Next.js app), [`frontend/src/services/api.js`](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/api.js) (API client), [`backend/modules/audio/audio.routes.js`](https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.routes.js) (Audio routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_web["Next.js app"]
  node_authui["Auth context<br/>[AuthContext.js]"]
  node_apisvc["API client<br/>[api.js]"]
  node_authsvcui["Auth client<br/>[authService.js]"]
  node_pdfui["PDF client<br/>[pdfService.js]"]
  node_imageui["Image client<br/>[imageService.js]"]
  node_musicui["Music client<br/>[musicService.js]"]
end

subgraph group_backend["API and access"]
  node_server["Express server<br/>[server.js]"]
  node_authroutes["Auth routes<br/>[auth.routes.js]"]
  node_authcontroller["Auth controller<br/>[auth.controller.js]"]
  node_authservice["Auth service<br/>[auth.service.js]"]
  node_guard["JWT guard<br/>[auth.middleware.js]"]
end

subgraph group_documents["PDF and images"]
  node_pdfroutes["PDF routes<br/>[pdf.routes.js]"]
  node_pdfcontroller["PDF controller<br/>[pdf.controller.js]"]
  node_pdfservice["PDF operations<br/>[pdf.service.js]"]
  node_imageroutes["Image routes<br/>[image.routes.js]"]
  node_imagecontroller["Image controller"]
  node_imageservice["Image operations<br/>[image.service.js]"]
end

subgraph group_audio["Audio processing"]
  node_audioroutes["Audio routes<br/>[audio.routes.js]"]
  node_audiocontroller["Audio controller"]
  node_audioservice["Audio tasks<br/>[audio.service.js]"]
  node_ytroutes["YouTube routes<br/>[youtube.routes.js]"]
  node_ytcontroller["YouTube controller"]
  node_ytservice["YouTube tasks<br/>[youtube.service.js]"]
end

subgraph group_state["Persistence and cleanup"]
  node_db[("PostgreSQL<br/>[db.js]")]
  node_temp[("Temp files")]
  node_cleanup["Cleanup service<br/>[cleanup.service.js]"]
end

node_user(("User"))
node_youtube(("YouTube"))

node_user -->|"uses"| node_web
node_web -->|"checks session"| node_authui
node_web -->|"requests auth"| node_authsvcui
node_web -->|"requests PDF"| node_pdfui
node_web -->|"requests images"| node_imageui
node_web -->|"requests audio"| node_musicui
node_authsvcui -->|"calls API"| node_apisvc
node_pdfui -->|"calls API"| node_apisvc
node_imageui -->|"calls API"| node_apisvc
node_musicui -->|"calls API"| node_apisvc
node_apisvc -->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_pdfroutes
node_server -->|"mounts routes"| node_imageroutes
node_server -->|"mounts routes"| node_audioroutes
node_server -->|"mounts routes"| node_ytroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_authcontroller -->|"calls"| node_authservice
node_authservice -->|"queries users"| node_db
node_pdfroutes -->|"authorizes"| node_guard
node_pdfroutes -->|"dispatches"| node_pdfcontroller
node_pdfcontroller -->|"calls"| node_pdfservice
node_imageroutes -->|"authorizes"| node_guard
node_imageroutes -->|"dispatches"| node_imagecontroller
node_imagecontroller -->|"calls"| node_imageservice
node_audioroutes -->|"authorizes"| node_guard
node_audioroutes -->|"dispatches"| node_audiocontroller
node_audiocontroller -->|"creates and polls"| node_audioservice
node_audioroutes -->|"stores uploads"| node_temp
node_audioservice -->|"reads and writes"| node_temp
node_ytroutes -->|"authorizes"| node_guard
node_ytroutes -->|"dispatches"| node_ytcontroller
node_ytcontroller -->|"creates and polls"| node_ytservice
node_ytservice -.->|"extracts audio"| node_youtube
node_ytservice -->|"stores output"| node_temp
node_cleanup -->|"cleans files"| node_temp
node_server -->|"starts cleanup"| node_cleanup

click node_web "https://github.com/qosam217/inst-sons/tree/main/frontend/src/app"
click node_authui "https://github.com/qosam217/inst-sons/blob/main/frontend/src/context/AuthContext.js"
click node_apisvc "https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/api.js"
click node_authsvcui "https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/authService.js"
click node_pdfui "https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/pdfService.js"
click node_imageui "https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/imageService.js"
click node_musicui "https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/musicService.js"
click node_server "https://github.com/qosam217/inst-sons/blob/main/backend/server.js"
click node_authroutes "https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.routes.js"
click node_authcontroller "https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.controller.js"
click node_authservice "https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.service.js"
click node_guard "https://github.com/qosam217/inst-sons/blob/main/backend/core/auth.middleware.js"
click node_pdfroutes "https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.routes.js"
click node_pdfcontroller "https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.controller.js"
click node_pdfservice "https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.service.js"
click node_imageroutes "https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.routes.js"
click node_imagecontroller "https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.controller.js"
click node_imageservice "https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.service.js"
click node_audioroutes "https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.routes.js"
click node_audiocontroller "https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.controller.js"
click node_audioservice "https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.service.js"
click node_ytroutes "https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.routes.js"
click node_ytcontroller "https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.controller.js"
click node_ytservice "https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.service.js"
click node_db "https://github.com/qosam217/inst-sons/blob/main/backend/core/db.js"
click node_temp "https://github.com/qosam217/inst-sons/tree/main/backend/temp"
click node_cleanup "https://github.com/qosam217/inst-sons/blob/main/backend/core/cleanup.service.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_web,node_authui,node_apisvc,node_authsvcui,node_pdfui,node_imageui,node_musicui,node_user toneBlue
class node_server,node_authroutes,node_authcontroller,node_authservice,node_guard toneAmber
class node_pdfroutes,node_pdfcontroller,node_pdfservice,node_imageroutes,node_imagecontroller,node_imageservice toneMint
class node_audioroutes,node_audiocontroller,node_audioservice,node_ytroutes,node_ytcontroller,node_ytservice toneRose
class node_db,node_temp,node_cleanup,node_youtube toneIndigo
```

## Components

### Web interface

- [Next.js app](https://github.com/qosam217/inst-sons/tree/main/frontend/src/app): `frontend/src/app`
- [Auth context](https://github.com/qosam217/inst-sons/blob/main/frontend/src/context/AuthContext.js): `frontend/src/context/AuthContext.js`
- [API client](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Auth client](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/authService.js): `frontend/src/services/authService.js`
- [PDF client](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/pdfService.js): `frontend/src/services/pdfService.js`
- [Image client](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/imageService.js): `frontend/src/services/imageService.js`
- [Music client](https://github.com/qosam217/inst-sons/blob/main/frontend/src/services/musicService.js): `frontend/src/services/musicService.js`

### API and access

- [Express server](https://github.com/qosam217/inst-sons/blob/main/backend/server.js): `backend/server.js`
- [Auth routes](https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.routes.js): `backend/modules/auth/auth.routes.js`
- [Auth controller](https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.controller.js): `backend/modules/auth/auth.controller.js`
- [Auth service](https://github.com/qosam217/inst-sons/blob/main/backend/modules/auth/auth.service.js): `backend/modules/auth/auth.service.js`
- [JWT guard](https://github.com/qosam217/inst-sons/blob/main/backend/core/auth.middleware.js): `backend/core/auth.middleware.js`

### PDF and images

- [PDF routes](https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.routes.js): `backend/modules/pdf/pdf.routes.js`
- [PDF controller](https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.controller.js): `backend/modules/pdf/pdf.controller.js`
- [PDF operations](https://github.com/qosam217/inst-sons/blob/main/backend/modules/pdf/pdf.service.js): `backend/modules/pdf/pdf.service.js`
- [Image routes](https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.routes.js): `backend/modules/image/image.routes.js`
- [Image controller](https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.controller.js): `backend/modules/image/image.controller.js`
- [Image operations](https://github.com/qosam217/inst-sons/blob/main/backend/modules/image/image.service.js): `backend/modules/image/image.service.js`

### Audio processing

- [Audio routes](https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.routes.js): `backend/modules/audio/audio.routes.js`
- [Audio controller](https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.controller.js): `backend/modules/audio/audio.controller.js`
- [Audio tasks](https://github.com/qosam217/inst-sons/blob/main/backend/modules/audio/audio.service.js): `backend/modules/audio/audio.service.js`
- [YouTube routes](https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.routes.js): `backend/modules/youtube/youtube.routes.js`
- [YouTube controller](https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.controller.js): `backend/modules/youtube/youtube.controller.js`
- [YouTube tasks](https://github.com/qosam217/inst-sons/blob/main/backend/modules/youtube/youtube.service.js): `backend/modules/youtube/youtube.service.js`

### Persistence and cleanup

- [PostgreSQL](https://github.com/qosam217/inst-sons/blob/main/backend/core/db.js): `backend/core/db.js`
- [Temp files](https://github.com/qosam217/inst-sons/tree/main/backend/temp): `backend/temp`
- [Cleanup service](https://github.com/qosam217/inst-sons/blob/main/backend/core/cleanup.service.js): `backend/core/cleanup.service.js`

### Other components

- **User**
- **YouTube**

## Connections

- User → Next.js app: uses
- Next.js app → Auth context: checks session
- Next.js app → Auth client: requests auth
- Next.js app → PDF client: requests PDF
- Next.js app → Image client: requests images
- Next.js app → Music client: requests audio
- Auth client → API client: calls API
- PDF client → API client: calls API
- Image client → API client: calls API
- Music client → API client: calls API
- API client → Express server: HTTP requests
- Express server → Auth routes: mounts routes
- Express server → PDF routes: mounts routes
- Express server → Image routes: mounts routes
- Express server → Audio routes: mounts routes
- Express server → YouTube routes: mounts routes
- Auth routes → Auth controller: dispatches
- Auth controller → Auth service: calls
- Auth service → PostgreSQL: queries users
- PDF routes → JWT guard: authorizes
- PDF routes → PDF controller: dispatches
- PDF controller → PDF operations: calls
- Image routes → JWT guard: authorizes
- Image routes → Image controller: dispatches
- Image controller → Image operations: calls
- Audio routes → JWT guard: authorizes
- Audio routes → Audio controller: dispatches
- Audio controller → Audio tasks: creates and polls
- Audio routes → Temp files: stores uploads
- Audio tasks → Temp files: reads and writes
- YouTube routes → JWT guard: authorizes
- YouTube routes → YouTube controller: dispatches
- YouTube controller → YouTube tasks: creates and polls
- YouTube tasks → YouTube: extracts audio
- YouTube tasks → Temp files: stores output
- Cleanup service → Temp files: cleans files
- Express server → Cleanup service: starts cleanup