How ssshogunn/lumina works
Main Components
• Frontend (User Interface): Notice the Next.js “app” folder under src/app that contains pages (dashboard, auth-callback, etc.) and many React components (Chat, NavBar, Providers, etc.). This is where the user interacts with the system.
• API / Backend Endpoints: The src/app/api directory contains several API route implementations including endpoints for authentication ([kindeAuth]), messages, tRPC calls, and file uploads. These endpoints implement the business logic for file processing, authentication (via KindeAuth), and AI querying.
• Business Logic / Services Layer: The src/lib directory houses modules for file uploading (likely interfacing with AWS S3), OpenAI integration (to handle AI responses), Pinecone vector DB operations (for smart indexing), and generic utilities or validators.
• Database Layer: The presence of a prisma folder (with schema.prisma) and a src/db folder indicates that your application uses Prisma as an ORM to interact with a Postgresql database. According to the README, the actual database service is Supabase.
• External Services: The system integrates with multiple third-party services:
• Authentication: KindeAuth for user sign up/log in.
• AI: OpenAI for generating responses based on PDF content.
• Vector Database: Pinecone for efficient document indexing.
• Cloud Storage: AWS S3 for storing PDF files.
Relationships and Data Flow
• Users interact with the Frontend (written in Next.js with React) which is composed of various pages and components.
• Once the user uploads a PDF via the intuitive drag-and-drop upload interface, the frontend calls the API endpoint in /src/app/api/upload. The file is then transferred to AWS S3 and its metadata is stored in the Postgresql database through Prisma.
• In parallel, the PDF content is processed: it’s likely sent to an OpenAI integration (in src/lib/openai.ts) to extract content for conversational use, and then indexed via Pinecone (in src/lib/pinecone.ts) for rapid document retrieval.
• The chat functionality is powered by specific APIs (see /src/app/api/message and TRPC endpoints in /src/app/api/trpc and src/trpc). This ensures the frontend chat components are decoupled but well-integrated with backend logic.
• User authentication flows through a dedicated auth route (/src/app/api/auth/[kindeAuth]) which interacts with KindeAuth externally.
Architectural Patterns and Design Principles
• Separation of Concerns: The project clearly separates the frontend UI, API logic, and external integrations (file upload, AI, vector DB) into distinct modules.
• Modular and Component-Based Design: The React components (in src/components) are focused on specific functionalities (Chat, Dashboard, UI components), which can be independently updated or reused.
• API Abstraction with tRPC: The use of tRPC in both the API and client components allows for strongly typed, end-to-end communication.
• Cloud and External Provider Integration: The architectural design embraces multiple external services (KindeAuth, AWS S3, Pinecone, OpenAI) and supports scalable, cloud-based interactions.
Technologies, Frameworks, and Libraries
• Next.js with TypeScript for building the full-stack application, including both server-rendered pages and API endpoints.
• Tailwind CSS for styling.
• Prisma as the ORM layer interacting with the Supabase (Postgresql) database.
• External SDKs and libraries for integration with KindeAuth, AWS S3, Pinecone, and OpenAI.
• tRPC for type-safe API communication between the frontend and backend.