How par4m/orb works
Project type and purpose
• UC ORB is a full-stack web application: a discovery tool to browse and search open-source UC repositories.
• Frontend: Next.js (React) with TailwindCSS, delivering UI and routing.
• Backend: FastAPI serving REST endpoints over Uvicorn, reading from a JSON data file (and potentially a database).
File structure
• Top level:
• backend/ – FastAPI application
• frontend/ – Next.js application
• backend/app/
• routers/ – HTTP route handlers (repositories.py)
• services/ – business logic (repository_service.py)
• models/ – Pydantic models (repository.py)
• data/ – mock data source (repositories.json)
• main.py – app entry point
• frontend/src/app/
• page.tsx – home, about, repository listing, repository detail pages
• layout.tsx – root layout (header/footer)
• globals.css – global styles
• [id]/page.tsx – dynamic routing for repo detail
• Config files: requirements.txt, package.json, next.config.js, tailwind.config.js, vercel.json
Extract additional insights from README
• Endpoints: GET /api/repositories, /campuses, /languages, /topics, /{repo_id}
• Search & filter capabilities live in frontend calling backend APIs
• Future extensibility: real database, GitHub API integration, authentication
a. Main components
1. Client Browser
2. Next.js Frontend (Hosting/Vercel)
– App Router pages, React components, TailwindCSS styling
3. REST API Layer (Frontend → Backend via fetch)
4. FastAPI Backend (Uvicorn)
– Routers (controllers), Services (business logic), Models (data schemas)
5. Data Layer
– Mock JSON file (repositories.json) or future PostgreSQL DB
6. External Services (optional)
– GitHub API, Authentication provider
b. Relationships & data flow
• Browser issues HTTP(S) requests to Next.js for pages (SSR/SSG)
• React code in pages calls fetch(“/api/repositories”) to Next.js API proxy
• Next.js API routes (if used) or direct client-to-backend calls route to FastAPI
• FastAPI routers call service layer → read JSON or query DB → return Pydantic models
• Backend returns JSON → React state updates UI
c. Architectural patterns & principles
• Layered architecture in backend (Router → Service → Data)
• File-system–based routing in Next.js (App Router)
• Separation of concerns: UI, API, business logic, data persistence
• Potential for microservices or external API integration
d. Key technologies/frameworks
• Frontend: Next.js 14, React Hooks, TailwindCSS, native Fetch API
• Backend: FastAPI, Uvicorn, Pydantic, python-dotenv
• Data: JSON file (repositories.json), future PostgreSQL
Detail
• Sub-component: React pages, API routers, service modules, data files
• Keep it updatable: show placeholder for future database or external API modules