# abdorabee/kanon architecture

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

- Interactive diagram: https://gitdiagram.com/abdorabee/kanon
- Repository: https://github.com/abdorabee/kanon

## Overview

##### Project Type and Purpose
- Kanon is a full-stack, server-rendered web application built on Next.js (v15) and React (v19).
- It serves as an AI-powered legal assistant, offering features like advanced legal research, document analysis, and case strategy development via AI/ML models.
- Containerized with Docker and orchestrated via docker-compose for local dev and production deployment.

##### File Structure Analysis
- src/app
- api/issues and api/session: Next.js API routes providing RESTful endpoints.
- components: Reusable UI building blocks (layout, ui).
- lib: Helper modules (api.ts for HTTP calls, sessionStorage.ts, translation.ts, type definitions).
- page.tsx and response/page.tsx: Main entrypoints for user workflows.
- middleware.ts: Cross-cutting logic (e.g., authentication, routing).
- public: Static assets, including translation JSON files.
- Configuration: next.config.ts, tsconfig.json, ESLint, PostCSS, Tailwind setup.
- DevOps: Dockerfile, docker-compose.yml, GitHub Actions workflows for CI/CD.

##### README Insights
- Emphasizes use of Next.js App Router, Tailwind CSS v4, Motion for animations.
- No built-in database folder—likely relies on external APIs or managed services (e.g., vector DB or OpenAI endpoints).
- Encourages environment variable configuration for secrets and endpoints.

##### Main Components to Model
a. Client Layer
- Browser (React components)
- Static assets CDN (public folder & translations)
b. Web Server Layer
- Next.js App Router (SSR & SSG pages)
- Next.js API Routes (/issues, /session)
- Middleware (authentication, routing)
c. Application Logic
- lib/api.ts: HTTP client to AI or legal data services
- lib/translation.ts: i18n loader
- lib/sessionStorage.ts: client-side session persistence
d. External Services
- AI/ML Service (OpenAI or custom endpoint)
- Legal Data Store (cases, statutes) or third-party APIs
- Logging/Monitoring (optional)
e. Infrastructure
- Docker Container
- Docker Compose (multi-service orchestration)
- CI/CD (GitHub Actions)

##### Relationships and Data Flow
- User → Browser: interact with React UI, choose actions.
- Browser → Next.js Server:
- Page requests (SSR/SSG) for landing, response screens.
- API calls→ /api/issues or /api/session.
- Next.js API Routes → Application Logic (lib/api.ts) → External AI/Data Services.
- Next.js Server → Browser: renders HTML + JSON payloads.
- Session Data flow: stored in browser sessionStorage, passed on subsequent requests.
- Docker Compose orchestrates local mock of any required ancillary services (e.g., local Key-Value store).

##### Architectural Patterns and Principles
- Component-Based UI (React + Next.js App Router).
- Thin API Layer: Next.js API Routes as micro-endpoints.
- Separation of Concerns: UI components vs. lib (domain logic) vs. external service adapters.
- Containerization: Immutable deployments via Docker.
- Internationalization: Static JSON translations served from public folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Browser (React UI)"]:::frontend
        subgraph "React Components" 
            direction TB
            MainLayout["MainLayout"]:::frontend
            Footer["Footer"]:::frontend
            Button["Button"]:::frontend
            CallToAction["CallToAction"]:::frontend
            FeatureCard["FeatureCard"]:::frontend
            Header["Header"]:::frontend
            Hero["Hero"]:::frontend
            PromptInput["PromptInput"]:::frontend
            ResponseDisplay["ResponseDisplay"]:::frontend
        end
        subgraph "Static Assets (CDN)" 
            direction TB
            TranslationsEN["en.json"]:::frontend
            TranslationsAR["ar.json"]:::frontend
        end
    end

    %% Web Server Layer
    subgraph "Web Server Layer" 
        direction TB
        subgraph "Next.js Application" 
            direction TB
            PageHome["page.tsx (Home)"]:::backend
            PageResponse["response/page.tsx"]:::backend
            layoutTS["layout.tsx"]:::backend
            globalsCSS["globals.css"]:::backend
        end
        Middleware["middleware.ts"]:::backend
        subgraph "API Routes" 
            direction TB
            IssuesAPI["/api/issues"]:::backend
            SessionAPI["/api/session/[id]"]:::backend
        end
    end

    %% Application Logic
    subgraph "Application Logic (lib)" 
        direction TB
        APIClient["api.ts"]:::backend
        TranslationLoader["translation.ts"]:::backend
        SessionStorage["sessionStorage.ts"]:::backend
        Types["types.ts"]:::backend
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        AIService["AI/ML Service"]:::external
        LegalDataStore[(Legal Data Store)]:::db
    end

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        DockerContainer["Docker Container"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        DockerIgnore[".dockerignore"]:::infra
        subgraph "CI/CD" 
            direction TB
            BuildCheck["build-check.yml"]:::infra
            DockerImageWF["docker-image.yml"]:::infra
        end
    end

    %% Data Flows
    Browser -->|"Request SSR/SSG"| PageHome
    Browser -->|"Request SSR/SSG"| PageResponse
    Browser -->|"POST /api/issues"| IssuesAPI
    Browser -->|"POST /api/session"| SessionAPI
    PageHome -->|“load translations”| TranslationLoader
    TranslationLoader -->|“fetch JSON”| TranslationsEN
    TranslationLoader -->|“fetch JSON”| TranslationsAR
    IssuesAPI -->|"calls"| APIClient
    SessionAPI -->|"calls"| APIClient
    APIClient -->|"query"| AIService
    APIClient -->|"fetch data"| LegalDataStore
    APIClient -->|“return result”| IssuesAPI
    APIClient -->|“return result”| SessionAPI
    PageHome -->|"render layout"| MainLayout
    PageResponse -->|"render layout"| MainLayout
    MainLayout --> Header
    MainLayout --> Hero
    MainLayout --> FeatureCard
    MainLayout --> CallToAction
    PageResponse --> PromptInput
    PageResponse --> ResponseDisplay
    Browser -->|"session persistence"| SessionStorage
    Middleware --> PageHome
    Middleware --> IssuesAPI
    Middleware --> SessionAPI
    DockerContainer --> PageHome
    DockerContainer --> IssuesAPI
    DockerContainer --> APIClient
    DockerCompose --> DockerContainer
    BuildCheck --> DockerContainer
    DockerImageWF --> DockerContainer

    %% Click events
    click MainLayout "https://github.com/abdorabee/kanon/blob/main/src/app/components/layout/MainLayout.tsx"
    click Footer "https://github.com/abdorabee/kanon/blob/main/src/app/components/layout/Footer.tsx"
    click Button "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/Button.tsx"
    click CallToAction "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/CallToAction.tsx"
    click FeatureCard "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/FeatureCard.tsx"
    click Header "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/Header.tsx"
    click Hero "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/Hero.tsx"
    click PromptInput "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/PromptInput.tsx"
    click ResponseDisplay "https://github.com/abdorabee/kanon/blob/main/src/app/components/ui/ResponseDisplay.tsx"
    click TranslationsEN "https://github.com/abdorabee/kanon/blob/main/public/translation/en.json"
    click TranslationsAR "https://github.com/abdorabee/kanon/blob/main/public/translation/ar.json"
    click PageHome "https://github.com/abdorabee/kanon/blob/main/src/app/page.tsx"
    click PageResponse "https://github.com/abdorabee/kanon/blob/main/src/app/response/page.tsx"
    click layoutTS "https://github.com/abdorabee/kanon/blob/main/src/app/layout.tsx"
    click globalsCSS "https://github.com/abdorabee/kanon/blob/main/src/app/globals.css"
    click IssuesAPI "https://github.com/abdorabee/kanon/blob/main/src/app/api/issues/route.ts"
    click SessionAPI "https://github.com/abdorabee/kanon/blob/main/src/app/api/session/[id]/route.ts"
    click Middleware "https://github.com/abdorabee/kanon/blob/main/src/middleware.ts"
    click APIClient "https://github.com/abdorabee/kanon/blob/main/src/app/lib/api.ts"
    click TranslationLoader "https://github.com/abdorabee/kanon/blob/main/src/app/lib/translation.ts"
    click SessionStorage "https://github.com/abdorabee/kanon/blob/main/src/app/lib/sessionStorage.ts"
    click Types "https://github.com/abdorabee/kanon/blob/main/src/app/lib/types.ts"
    click DockerContainer "https://github.com/abdorabee/kanon/tree/main/Dockerfile"
    click DockerCompose "https://github.com/abdorabee/kanon/blob/main/docker-compose.yml"
    click DockerIgnore "https://github.com/abdorabee/kanon/blob/main/.dockerignore"
    click BuildCheck "https://github.com/abdorabee/kanon/blob/main/.github/workflows/build-check.yml"
    click DockerImageWF "https://github.com/abdorabee/kanon/blob/main/.github/workflows/docker-image.yml"

    %% Class Definitions
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef backend fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#fff3cd,stroke:#ffce54,color:#000;
    classDef db fill:#f8d7da,stroke:#dc3545,color:#000,stroke-dasharray: 3 2;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#000;
```
