# nyangoto/pawait-assessment architecture

> Architecture diagram of the GitHub repository nyangoto/pawait-assessment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nyangoto/pawait-assessment
- Repository: https://github.com/nyangoto/pawait-assessment

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["Browser/Device"]:::user

    subgraph "Frontend Layer"
        FEApp["Next.js App"]:::frontend
        ChatPage["Chat Page"]:::frontend
        LoginPage["Login Page"]:::frontend
        RegisterPage["Register Page"]:::frontend
        SettingsPage["Settings Page"]:::frontend
        ApiClient["API Client (/api/v1)"]:::frontend
        SupabaseJS["Supabase JS Client"]:::frontend
        ChatStore["Zustand Chat Store"]:::frontend
        AuthContext["Auth Context"]:::frontend
        LocalHistory["useLocalHistory Hook"]:::frontend
        ChatUI["Chat UI Components"]:::frontend
        GuestPrompt["Guest Prompt Component"]:::frontend
        LayoutComps["Layout Components"]:::frontend
        SettingsComps["Theme & LLM Selector Components"]:::frontend

        FEApp --> ChatPage
        FEApp --> LoginPage
        FEApp --> RegisterPage
        FEApp --> SettingsPage
        ChatPage --> ChatUI
        ChatPage --> ChatStore
        ChatPage --> GuestPrompt
        SettingsPage --> SettingsComps
        FEApp --> AuthContext
        AuthContext --> SupabaseJS
        FEApp --> ApiClient
        ChatStore --> LocalHistory
    end

    User --> FEApp
    FEApp --> ApiClient

    subgraph "Backend Layer"
        BackendAPI["FastAPI API (/api/v1)"]:::backend
        BackendMain["FastAPI App"]:::backend
        Deps["API Dependencies"]:::backend
        ConvEndpoint["Conversation Endpoint"]:::backend
        CoreConfig["Core Config"]:::backend
        Security["Security (JWT)"]:::backend
        SupaClient["Supabase Python Client"]:::backend
        LLMBase["LLM Base Adapter"]:::backend
        LLMFactory["LLM Factory"]:::backend
        ConvService["Conversation Service"]:::backend
        ConvSchemas["Conversation Schemas"]:::backend

        ApiClient --> BackendAPI
        BackendAPI --> BackendMain
        BackendMain --> Deps
        Deps --> Security
        BackendMain --> ConvEndpoint
        ConvEndpoint --> ConvService
        ConvService --> SupaClient
        ConvService --> LLMFactory
        ConvService --> ConvSchemas
        LLMFactory --> LLMBase
        CoreConfig --> BackendMain
        Security --> SupaClient
    end

    subgraph "Data Store & Auth"
        SupabaseDB["Supabase PostgreSQL"]:::db
        SupabaseAuth["Supabase Auth"]:::db
        SupaClient --> SupabaseDB
        Security --> SupabaseAuth
    end

    subgraph "External LLM Providers"
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
        Gemini["Google Gemini API"]:::external

        LLMBase --> OpenAI
        LLMBase --> Anthropic
        LLMBase --> Gemini
    end

    subgraph "Infrastructure & Docs"
        DockerCompose["docker-compose.yml"]:::infra
        Docs["Design Docs"]:::infra
    end

    classDef frontend fill:#D0E8FF,stroke:#000
    classDef backend fill:#C8E6C9,stroke:#000
    classDef db fill:#FFE0B2,stroke:#000
    classDef external fill:#E1BEE7,stroke:#000
    classDef user fill:#ECEFF1,stroke:#000
    classDef infra fill:#F5F5F5,stroke:#000

    click FEApp "https://github.com/nyangoto/pawait-assessment/tree/main/frontend/src/app"
    click ChatPage "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/app/chat/[[...conversationId]]/page.tsx"
    click LoginPage "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/app/login/page.tsx"
    click RegisterPage "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/app/register/page.tsx"
    click SettingsPage "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/app/settings/page.tsx"
    click SupabaseJS "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/lib/supabaseClient.ts"
    click ApiClient "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/services/apiClient.ts"
    click ChatStore "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/stores/chatStore.ts"
    click AuthContext "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/contexts/AuthContext.tsx"
    click LocalHistory "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/hooks/useLocalHistory.ts"
    click ChatUI "https://github.com/nyangoto/pawait-assessment/tree/main/frontend/src/components/chat"
    click GuestPrompt "https://github.com/nyangoto/pawait-assessment/blob/main/frontend/src/components/guest/GuestPrompt.tsx"
    click LayoutComps "https://github.com/nyangoto/pawait-assessment/tree/main/frontend/src/components/layout"
    click SettingsComps "https://github.com/nyangoto/pawait-assessment/tree/main/frontend/src/components/settings"
    click BackendMain "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/main.py"
    click Deps "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/api/deps.py"
    click ConvEndpoint "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/api/endpoints/conversation.py"
    click CoreConfig "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/core/config.py"
    click Security "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/core/security.py"
    click SupaClient "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/db/supabase_client.py"
    click LLMBase "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/llm/base.py"
    click LLMFactory "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/llm/factory.py"
    click ConvService "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/services/conversation.py"
    click ConvSchemas "https://github.com/nyangoto/pawait-assessment/blob/main/backend/app/schemas/conversation.py"
    click DockerCompose "https://github.com/nyangoto/pawait-assessment/blob/main/docker-compose.yml"
    click Docs "https://github.com/nyangoto/pawait-assessment/tree/main/docs"
```
