# sungurulol/a3i-akademik-asistan architecture

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

- Interactive diagram: https://gitdiagram.com/sungurulol/a3i-akademik-asistan
- Repository: https://github.com/sungurulol/a3i-akademik-asistan

## Overview

A³I is a local-first academic research assistant: users work in a browser UI, send requests through a local Node backend, and receive streamed Claude Code results backed by academic-research skills. The README also documents file processing, chat memory, and document/presentation exports. Backend excerpts are partial, so some feature wiring is represented only where the README or sampled handlers support it; the macOS and Windows trees contain parallel implementations.

Main entry points: [`macOS/backend/server.js`](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js) (Local API and stream), [`macOS/frontend/index.html`](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/frontend/index.html) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_browser(("Browser"))
  node_ui["Web interface<br/>[index.html]"]
  node_backend["Local API and stream<br/>[server.js]"]
  node_session["Session and model control<br/>[server.js]"]
end

subgraph group_research["Academic work"]
  node_claude["Claude Code"]
  node_skills["Academic research skills"]
  node_research_modes["Research and writing"]
  node_qual_analysis["Qualitative analysis"]
  node_peer_review["Peer review"]
  node_guided_questions["Guided questions"]
end

subgraph group_files["Files and exports"]
  node_uploads["Upload processing<br/>[server.js]"]
  node_pdf_parser["PDF parser"]
  node_markitdown["MarkItDown"]
  node_doc_export["DOCX and PDF export<br/>[server.js]"]
  node_slides["Presentation export<br/>[server.js]"]
  node_file_pane["Generated files pane<br/>[index.html]"]
end

subgraph group_state["Local state"]
  node_downloads[("Downloads directory<br/>[server.js]")]
  node_chat_memory["Chat memory and search<br/>[server.js]"]
  node_chats[("Chats directory<br/>[server.js]")]
end

node_user(("Researcher"))

node_user -->|"uses"| node_browser
node_browser -->|"displays"| node_ui
node_ui -->|"sends requests"| node_backend
node_backend -->|"streams results"| node_ui
node_backend -->|"manages sessions"| node_session
node_session -->|"starts and resumes"| node_claude
node_claude -->|"streams output"| node_backend
node_claude -->|"uses"| node_skills
node_skills -->|"supports"| node_research_modes
node_skills -->|"supports"| node_qual_analysis
node_skills -->|"supports"| node_peer_review
node_ui -->|"requests"| node_guided_questions
node_backend -->|"handles uploads"| node_uploads
node_uploads -->|"parses PDFs"| node_pdf_parser
node_uploads -->|"converts other files"| node_markitdown
node_backend -->|"prepares exports"| node_doc_export
node_backend -->|"runs export skill"| node_slides
node_doc_export -->|"writes files"| node_downloads
node_slides -->|"writes files"| node_downloads
node_downloads -->|"lists downloadable files"| node_file_pane
node_backend -->|"serves chat operations"| node_chat_memory
node_chat_memory -->|"reads and writes"| node_chats
node_file_pane -->|"requests file list"| node_backend

click node_ui "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/frontend/index.html"
click node_backend "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_session "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_uploads "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_doc_export "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_slides "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_file_pane "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/frontend/index.html"
click node_downloads "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_chat_memory "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js"
click node_chats "https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.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_browser,node_ui,node_backend,node_session toneBlue
class node_claude,node_skills,node_research_modes,node_qual_analysis,node_peer_review,node_guided_questions toneAmber
class node_uploads,node_pdf_parser,node_markitdown,node_doc_export,node_slides,node_file_pane toneMint
class node_downloads,node_chat_memory,node_chats toneRose
class node_user toneIndigo
```

## Components

### User interaction

- **Browser**
- [Web interface](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/frontend/index.html): `macOS/frontend/index.html`
- [Local API and stream](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- [Session and model control](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`

### Academic work

- **Claude Code**
- **Academic research skills**
- **Research and writing**
- **Qualitative analysis**
- **Peer review**
- **Guided questions**

### Files and exports

- [Upload processing](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- **PDF parser**
- **MarkItDown**
- [DOCX and PDF export](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- [Presentation export](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- [Generated files pane](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/frontend/index.html): `macOS/frontend/index.html`

### Local state

- [Downloads directory](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- [Chat memory and search](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`
- [Chats directory](https://github.com/sungurulol/a3i-akademik-asistan/blob/main/macOS/backend/server.js): `macOS/backend/server.js`

### Other components

- **Researcher**

## Connections

- Researcher → Browser: uses
- Browser → Web interface: displays
- Web interface → Local API and stream: sends requests
- Local API and stream → Web interface: streams results
- Local API and stream → Session and model control: manages sessions
- Session and model control → Claude Code: starts and resumes
- Claude Code → Local API and stream: streams output
- Claude Code → Academic research skills: uses
- Academic research skills → Research and writing: supports
- Academic research skills → Qualitative analysis: supports
- Academic research skills → Peer review: supports
- Web interface → Guided questions: requests
- Local API and stream → Upload processing: handles uploads
- Upload processing → PDF parser: parses PDFs
- Upload processing → MarkItDown: converts other files
- Local API and stream → DOCX and PDF export: prepares exports
- Local API and stream → Presentation export: runs export skill
- DOCX and PDF export → Downloads directory: writes files
- Presentation export → Downloads directory: writes files
- Downloads directory → Generated files pane: lists downloadable files
- Local API and stream → Chat memory and search: serves chat operations
- Chat memory and search → Chats directory: reads and writes
- Generated files pane → Local API and stream: requests file list