How aliaitrhou/shell-agent works
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