# aliaitrhou/shell-agent architecture

> Architecture diagram of the GitHub repository aliaitrhou/shell-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aliaitrhou/shell-agent
- Repository: https://github.com/aliaitrhou/shell-agent

## Overview

##### Project type and purpose
- AceOS is a full-stack, Next.js-based web application that provides an interactive, chat-like terminal interface for learning Linux commands.
- It combines a React/Next.js frontend, internal API routes in the app directory, a Prisma-backed database, and AI/RAG services for contextual answers.

##### File structure
- Top-level “app” directory: Next.js App Router.
- app/page.tsx, app/layout.tsx, app/globals.css: global layout and styling.
- app/api/*: serverless REST/HTTP endpoints for chats, messages, model, cmd.
- “components” folder: UI components (chat window, terminal, sidebar, buttons, PDF preview, etc.).
- “lib” folder: shared utilities and Prisma client (lib/prisma.ts, lib/utils.ts).
- “prisma” folder: database schema, migrations.
- “public/course-s3” & “public/course-s4”: static PDF assets used for RAG.
- Configuration files: next.config.ts, tailwind.config.ts, tsconfig.json.

##### Key insights from README
- Uses Retrieval-Augmented Generation: queries vector store / PDF corpus to ground AI responses in real course material.
- AI-Powered explanations: likely OpenAI (or similar) called in app/api/model/route.ts.
- Terminal UI built from custom React components.

##### Main components
a. Frontend (Next.js App Router)
– Components: page.tsx → UI components (chat window, terminal, sidebar, PDF preview)
– CSS/Tailwind styling
b. Backend/API (Next.js serverless functions)
– Endpoints:
- /api/chats → create/list chat sessions
- /api/messages/[chatId] → fetch/send messages
- /api/cmd → run shell commands (simulated)
- /api/model → invoke AI model with RAG
– Utilities: lib/utils (prompt building, RAG logic)
– Prisma client: lib/prisma → database CRUD for chats & messages
c. Database
– PostgreSQL (or MySQL/SQLite) via Prisma ORM
– Tables: Chat, Message (with role, content, timestamp)
d. RAG/AI External Services
– Vector store or embedding service (e.g., Pinecone, Weaviate)
– OpenAI (or local LLM) for text completion/explanation
– PDF documents stored in public/ for retrieval
e. Static Asset Store
– Next.js public/ folder hosting course PDFs

##### Relationships & Data Flow
- User interacts with Terminal UI → Frontend issues HTTP requests to API endpoints.
- API layer:
- For chat/message endpoints → Prisma client reads/writes to DB.
- For model endpoint → lib/utils orchestrates RAG:
– Extract relevant passages from PDFs → embed/query vector store.
– Call AI service with context → return answer.
- For cmd endpoint → sanitize & simulate shell command, return output.
- DB persists conversation history.
- Frontend polls or streams new messages & renders them in MarkdownRenderer.

##### Architectural patterns & design principles
- MVC-style separation:
- View = React components + pages
- Controller = API routes
- Model = Prisma ORM + database schema
- RAG pipeline: modular retrieval + generation
- Component-based UI with reusable pieces (buttons, alerts, terminal blocks)
- Serverless functions for scale & isolation of concerns

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client/Browser"
        direction TB
        Page["page.tsx"]:::frontend
        Layout["layout.tsx"]:::frontend
        Globals["globals.css"]:::frontend
        subgraph "UI Components"
            direction TB
            ChatWindow["ChatMessages"]:::frontend
            Terminal["Terminal"]:::frontend
            TerminalPrompt["TerminalPrompt"]:::frontend
            TerminalTopBar["TerminalTopBar"]:::frontend
            Sidebar["Sidebar"]:::frontend
            PDFPreview["PDFPreview"]:::frontend
            Button["ButtonHoverEffect"]:::frontend
            Markdown["MarkdownRenderer"]:::frontend
            ChatItem["ChatItem"]:::frontend
            ChatWrapper["ChatItemWrapper"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Server/Backend"
        direction TB
        subgraph "API Endpoints"
            direction TB
            Chats["/api/chats"]:::backend
            Messages["/api/messages/:chatId"]:::backend
            Cmd["/api/cmd"]:::backend
            Model["/api/model"]:::backend
        end
        subgraph "Utilities & ORM"
            direction TB
            Utils["lib/utils"]:::backend
            PrismaClient["Prisma Client"]:::backend
            Schema["schema.prisma"]:::backend
            Migrations["migrations"]:::backend
        end
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        Database["PostgreSQL"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        VectorStore["Vector Store"]:::external
        AIService["AI Completion Service"]:::external
        CourseS3["course-s3 PDFs"]:::external
        CourseS4["course-s4 PDF"]:::external
    end

    %% Data Flows
    Terminal -->|"POST /api/cmd"| Cmd
    ChatWindow -->|"GET/POST /api/messages"| Messages
    PDFPreview -->|"POST /api/model"| Model
    Markdown -->|"GET /api/messages"| Messages

    Chats --> PrismaClient
    Messages --> PrismaClient
    Model --> Utils
    Model --> PrismaClient
    Cmd --> Utils

    PrismaClient --> Database

    Utils --> VectorStore
    Utils --> AIService
    Utils --> CourseS3
    Utils --> CourseS4

    %% Click Events
    click Page "https://github.com/aliaitrhou/shell-agent/blob/main/app/page.tsx"
    click Layout "https://github.com/aliaitrhou/shell-agent/blob/main/app/layout.tsx"
    click Globals "https://github.com/aliaitrhou/shell-agent/blob/main/app/globals.css"
    click ChatWindow "https://github.com/aliaitrhou/shell-agent/blob/main/components/chat-messages.tsx"
    click Terminal "https://github.com/aliaitrhou/shell-agent/blob/main/components/terminal.tsx"
    click TerminalPrompt "https://github.com/aliaitrhou/shell-agent/blob/main/components/terminal-prompt.tsx"
    click TerminalTopBar "https://github.com/aliaitrhou/shell-agent/blob/main/components/terminal-top-bar.tsx"
    click Sidebar "https://github.com/aliaitrhou/shell-agent/blob/main/components/sidebar.tsx"
    click PDFPreview "https://github.com/aliaitrhou/shell-agent/blob/main/components/pdf-preview.tsx"
    click Button "https://github.com/aliaitrhou/shell-agent/blob/main/components/button-hover-effect.tsx"
    click Markdown "https://github.com/aliaitrhou/shell-agent/blob/main/components/MarkdownRenderer.tsx"
    click ChatItem "https://github.com/aliaitrhou/shell-agent/blob/main/components/chat-item.tsx"
    click ChatWrapper "https://github.com/aliaitrhou/shell-agent/blob/main/components/chat-item-wrapper.tsx"
    click Chats "https://github.com/aliaitrhou/shell-agent/blob/main/app/api/chats/route.ts"
    click Messages "https://github.com/aliaitrhou/shell-agent/blob/main/app/api/messages/[chatId]/route.ts"
    click Cmd "https://github.com/aliaitrhou/shell-agent/blob/main/app/api/cmd/route.ts"
    click Model "https://github.com/aliaitrhou/shell-agent/blob/main/app/api/model/route.ts"
    click Utils "https://github.com/aliaitrhou/shell-agent/blob/main/lib/utils.ts"
    click PrismaClient "https://github.com/aliaitrhou/shell-agent/blob/main/lib/prisma.ts"
    click Schema "https://github.com/aliaitrhou/shell-agent/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/aliaitrhou/shell-agent/tree/main/prisma/migrations"
    click CourseS3 "https://github.com/aliaitrhou/shell-agent/tree/main/public/course-s3"
    click CourseS4 "https://github.com/aliaitrhou/shell-agent/blob/main/public/course-s4/course-s4.pdf"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#036,stroke-width:1px
    classDef backend fill:#E0FFE0,stroke:#090,stroke-width:1px
    classDef database fill:#FFF3E0,stroke:#F80,stroke-width:1px
    classDef external fill:#F3E0FF,stroke:#909,stroke-width:1px
```
