How mayagao/spaces works
Project Type and Purpose
• This is a full-stack React application built with Next.js (App Router).
• It provides a conversational UI (“chat”) across multiple “spaces,” plus GitHub-driven resource browsing and filterable conversation lists.
High-Level Architecture Components
a. Client (Browser)
• Loads the Next.js app over HTTP/HTTPS.
• Renders React components (mix of Server and Client Components).
b. Next.js Framework
• App Router (src/app/*) manages routing and layout.
• Builds server-rendered pages (SSR/SSG) and hydrates to the client.
c. UI Component Libraries
• Shared primitives under src/components/ui.
• Feature components under src/app/components (chat/, shared/, spaces/).
d. State & Context
• React Context at src/app/contexts (e.g. SidebarContext).
e. Data Layer
• Mock data in src/app/data/mockConversations.ts and preconfigured “spaceConversations” at src/app/data/spaceConversations/*.
• Services in src/app/services/githubService.ts for GitHub API calls.
• Utility functions in src/lib/utils.ts.
f. External Services
• GitHub REST API (used via githubService).
• Any external search or API clients in spaceConversations (capi, blackbirdSearch, etc.).
g. Static & Public Assets
• public/ directory for images, fonts, favicon.
• Tailwind, PostCSS configs and Next.js font optimization.
Relationships & Data Flows
1. User → Browser
2. Browser → Next.js Server (initial page load)
• Next.js App Router reads src/app/layout.tsx, page.tsx, pipes, etc.
3. Next.js Server → Data Layer
• Server Components call mock data modules or githubService.
• On client transitions, client components fetch data client-side.
4. Next.js → External APIs
• githubService.ts → GitHub API
• spaceConversations modules → third-party endpoints
5. Server/Client → React Components
• Layout → Sidebar, Header, PageTitle, ConversationList, ChatInput/Output, etc.
6. Browser ← Hydrated React App
Architectural Patterns & Principles
• MVC-like separation:
• “Views” are your React components in src/app/components.
• “Controllers/Services” are your modules under src/app/services and data connectors.
• App Router enforces layout nesting (layout.tsx under each route folder).
• Shared UI primitives (atoms) vs feature components.
• Context for cross-cutting state (e.g. sidebar open/close).
• CSS Modules / Tailwind for styling at the component level.
Essential Elements
• Clear component boundaries (Next.js vs UI library vs data service).
• Labels referencing key files/folders.