How nyangoto/pawait-assessment works
Project Type and Purpose
• Full-stack, conversational tax assistant.
• Frontend: Next.js/React app (SSR + CSR).
• Backend: FastAPI service.
• Database & Auth: Supabase (PostgreSQL + Auth).
• External AI: LLM providers (OpenAI, Anthropic, Google Gemini).
File Structure
a. Top-level directories:
• backend/ – FastAPI service (app/api, app/core, app/db, app/llm, app/services, schemas).
• frontend/ – Next.js 14 app router (src/app, components, contexts, hooks, services, stores).
• docs/ – design docs and specifications.
b. Key config & infra:
• backend/.env.example, Dockerfile, docker-compose.yml
• frontend/.env.local.example, next.config.js, tailwind.config.ts
c. Architectural patterns:
• Monorepo with clear separation of concerns.
• API-driven: frontend ↔ backend REST API (/api/v1).
• Service layer in backend (ConversationService).
• LLM factory/adapter pattern in app/llm.
Extract Insights from README
• Tech stack details (Next.js SSR, FastAPI async, Supabase RLS).
• Features: guest vs. authenticated flows, multi-turn context, history migration.
• Deployment: Vercel for frontend, container or ASGI server for backend.
• CI/CD: GitHub Actions.
a. User Clients
• Browser/Device
• Guest (localStorage) vs. Authenticated (Supabase Auth)
b. Frontend (Next.js + React)
• App Router pages (chat, login, register, settings)
• Zustand stores, React contexts, TailwindCSS styling
• Supabase JS client (auth + data)
• API client to Backend (/api/v1)
c. Backend (FastAPI)
• API Layer (endpoints: conversation, users, messages)
• Core (config, security)
• DB Module (Supabase Python client)
• LLM Layer (factory, adapters to OpenAI/Gemini/Claude)
• Services (ConversationService: business logic)
• Schemas (Pydantic models)
d. Data Store & Auth
• Supabase PostgreSQL (conversations, messages tables + RLS)
• Supabase Auth (JWT)
e. External Services
• OpenAI API
• Anthropic API
• Google Gemini API
Relationships & Data Flow
1) User interacts with Next.js UI (SSR/CSR).
2) Next.js either serves from Vercel or local dev; it calls FastAPI via HTTP.
3) FastAPI authenticates request via Supabase Auth (JWT).
4) FastAPI services query Supabase DB (via Supabase Python client).
5) For AI responses, FastAPI LLM layer calls external LLM APIs.
6) Responses are marshaled (Pydantic schemas) back to frontend.
7) Frontend updates Zustand store & optionally persists guest history to localStorage or invokes migration endpoint.
Architectural Patterns & Principles
• Separation of concerns (monorepo, distinct frontend/backend).
• Adapter/Factory for pluggable LLM integrations.
• API-First design with typed schemas (Pydantic + TypeScript).
• Secure by design: JWT Auth, Supabase RLS.
• SSR + CSR hybrid for performance and SEO.
• Feature-based modules (chat, auth, settings).
Essential Elements Checklist
• [ ] Components: Browser, Next.js, FastAPI, Supabase Auth, Supabase DB, LLM Providers
• [ ] Labels: Endpoints (/api/v1/message, /conversations, /users/migrate-history)
• [ ] Annotations: Feature bullets (multi-turn context, history migration)