# code/app-nous architecture

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

- Interactive diagram: https://gitdiagram.com/code/app-nous
- Repository: https://github.com/code/app-nous

## Overview

##### Project type and purpose
- This is a full-stack TypeScript monorepo (“TypedAI”) providing:
- Backend API server (Fastify) exposing REST/HTTP routes for agents, chatbots, code reviews, workflows, authentication, etc.
- Frontend Angular web app serving UI for agent management, chat, code review, user profile.
- CLI tool for local agent/workflow invocation.
- Autonomous AI agent engine and LLM orchestration platform.
- Pluggable “functions” and integrations (filesystem, Slack, Jira, GitHub, Google Cloud, etc.).
- Persisted state via in-memory or Firestore, optional PostgreSQL for function caching.
- Observability via OpenTelemetry tracing.

##### File structure
- Top-level:
- frontend/ – Angular UI
- src/fastify/ – Fastify application, middleware, routes
- src/cli/ – CLI entrypoints and commands
- src/agent/, src/llm/, src/chat/, src/functions/, src/modules/, src/routes/, src/swe/, etc. – Core engine libraries, services, workflows, modules
- shared/ – shared config and route definitions
- docs/ – MkDocs site and CLI scripts
- Dockerfile, docker-compose.yml – container build & local dev
- .github/workflows – CI & integration tests

##### README for additional insights
- Confirms full-featured AI platform:
- Autonomous agents & software engineer agents
- Code review agents
- Chat interface + Slack chatbot
- CLI + Web UI
- Multiple LLM services supported (OpenAI, Anthropic, Gemini, etc.)
- Function schema generation from decorated methods

##### Be very detailed
- Mock-api module used by the UI in development.
- DevOps build/test pipelines (CI workflows, Docker images).
- Authentication middleware (JWT, SSO) and observability hooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["Angular UI"]:::frontend
        CLI["CLI Application"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["Fastify Server"]:::backend
        subgraph "Routes"
            direction TB
            AgentRoutes["Agent Routes"]:::backend
            ChatRoutes["Chat Routes"]:::backend
            LLMSRoutes["LLM Routes"]:::backend
            AuthRoutes["Auth Routes"]:::backend
            WorkflowRoutes["Workflow Routes"]:::backend
            SCMRoutes["SCM/Code Review Routes"]:::backend
            WebhookRoutes["Webhook Routes"]:::backend
        end
        AuthMiddleware["Authentication Middleware"]:::backend
        JWT["JWT Module"]:::backend
    end

    %% Engine Layer
    subgraph "Engine Layer"
        direction TB
        Orchestrator["Agent Orchestrator / Runner"]:::engine
        HumanLoop["Human-in-the-Loop Support"]:::engine
        LLMCService["LLM Call Service"]:::engine
        LLFactory["LLM Factory"]:::engine
        FuncRegistry["Function Registry & Decorators"]:::engine
        subgraph "Core Modules"
            direction TB
            ChatService["Chat Service"]:::engine
            CodeReviewAgent["Code Review Agent"]:::engine
            SWEAgent["Software Engineer Agent"]:::engine
        end
    end

    %% Integration Layer
    subgraph "Integration / Functions"
        direction TB
        Functions["Functions Modules"]:::plugin
        SCMInt["SCM Integrations"]:::plugin
        CloudInt["Cloud Integrations"]:::plugin
        StorageInt["Storage Integrations"]:::plugin
        JiraInt["Jira Integration"]:::plugin
        GmailInt["Gmail (Email)"]:::plugin
    end

    %% Data Layer
    subgraph "Persistence Layer"
        direction TB
        Firestore["Firestore Backend"]:::persistence
        MemoryDB["In-Memory Backend"]:::persistence
        PGCache["PostgreSQL Function Cache"]:::persistence
    end

    %% Observability
    subgraph "Observability"
        direction TB
        FastifyTrace["Fastify Instrumentation"]:::o11y
        Tracer["Tracer"]:::o11y
        Logger["Logger"]:::o11y
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Providers"]:::external
        ThirdParty["Third-Party Services (Slack, Jira, GitHub)"]:::external
        FileSystem["Local File System"]:::external
    end

    %% Connections
    UI -->|"HTTP(S)"| API
    CLI -->|"HTTP or Local Calls"| API
    CLI -->|"Local Library"| Orchestrator
    API -->|"routes invoke"| AgentRoutes
    API -->|invoke| ChatRoutes
    API -->|invoke| LLMSRoutes
    API -->|invoke| AuthRoutes
    API -->|invoke| WorkflowRoutes
    API -->|invoke| SCMRoutes
    API -->|invoke| WebhookRoutes
    API -->|uses| AuthMiddleware
    AuthMiddleware -->|uses| JWT

    AgentRoutes -->|calls| Orchestrator
    ChatRoutes -->|calls| ChatService
    LLMSRoutes -->|calls| LLMCService
    WorkflowRoutes -->|triggers| Orchestrator
    SCMRoutes -->|calls| CodeReviewAgent
    WebhookRoutes -->|calls| FuncRegistry

    Orchestrator -->|uses| LLMCService
    Orchestrator -->|uses| FuncRegistry
    Orchestrator -->|uses| HumanLoop
    ChatService -->|uses| LLMCService
    CodeReviewAgent -->|uses| LLMCService
    SWEAgent -->|uses| LLMCService

    LLMCService -->|calls| LLFactory
    FuncRegistry -->|loads| Functions
    Functions -->|contains| SCMInt
    Functions -->|contains| CloudInt
    Functions -->|contains| StorageInt
    Functions -->|contains| JiraInt
    Functions -->|contains| GmailInt

    Orchestrator -->|persists| Firestore
    ChatService -->|persists| Firestore
    CodeReviewAgent -->|persists| PGCache
    LLMCService -->|persists| MemoryDB

    LLMCService -->|external API calls| LLMProviders
    Functions -->|integration calls| ThirdParty
    SWEAgent -->|file ops| FileSystem

    %% Observability Hooks (dotted)
    API -.-> FastifyTrace
    API -.-> Tracer
    Orchestrator -.-> Tracer
    LLMCService -.-> Tracer
    FuncRegistry -.-> Logger

    %% Click Events
    click UI "https://github.com/code/app-nous/tree/main/frontend/"
    click CLI "https://github.com/code/app-nous/tree/main/src/cli/"
    click API "https://github.com/code/app-nous/tree/main/src/fastify/"
    click AgentRoutes "https://github.com/code/app-nous/tree/main/src/routes/agent/"
    click ChatRoutes "https://github.com/code/app-nous/tree/main/src/routes/chat/"
    click LLMSRoutes "https://github.com/code/app-nous/tree/main/src/routes/llms/"
    click AuthRoutes "https://github.com/code/app-nous/tree/main/src/routes/auth/"
    click WorkflowRoutes "https://github.com/code/app-nous/tree/main/src/routes/workflows/"
    click SCMRoutes "https://github.com/code/app-nous/blob/main/src/routes/scm/codeReviewRoutes.ts"
    click WebhookRoutes "https://github.com/code/app-nous/tree/main/src/routes/webhooks/"
    click AuthMiddleware "https://github.com/code/app-nous/blob/main/src/fastify/authenticationMiddleware.ts"
    click JWT "https://github.com/code/app-nous/blob/main/src/fastify/jwt.ts"
    click Orchestrator "https://github.com/code/app-nous/blob/main/src/agent/agentWorkflowRunner.ts"
    click Orchestrator "https://github.com/code/app-nous/blob/main/src/agent/agentRunner.ts"
    click HumanLoop "https://github.com/code/app-nous/blob/main/src/agent/humanInTheLoop.ts"
    click LLMCService "https://github.com/code/app-nous/blob/main/src/llm/llmCallService/llmCallService.ts"
    click LLMCService "https://github.com/code/app-nous/blob/main/src/llm/llmCallService/llmCall.ts"
    click LLFactory "https://github.com/code/app-nous/blob/main/src/llm/llmFactory.ts"
    click FuncRegistry "https://github.com/code/app-nous/blob/main/src/functionRegistry.ts"
    click FuncRegistry "https://github.com/code/app-nous/blob/main/src/functionSchema/functionDecorators.ts"
    click FuncRegistry "https://github.com/code/app-nous/blob/main/src/functionSchema/functionSchemaParser.ts"
    click ChatService "https://github.com/code/app-nous/blob/main/src/chat/chatService.test.ts"
    click CodeReviewAgent "https://github.com/code/app-nous/blob/main/src/agent/codeGenAgentCodeReview.ts"
    click SWEAgent "https://github.com/code/app-nous/blob/main/src/swe/softwareDeveloperAgent.ts"
    click Functions "https://github.com/code/app-nous/tree/main/src/functions/"
    click SCMInt "https://github.com/code/app-nous/tree/main/src/functions/scm/"
    click CloudInt "https://github.com/code/app-nous/tree/main/src/functions/cloud/"
    click StorageInt "https://github.com/code/app-nous/tree/main/src/functions/storage/"
    click JiraInt "https://github.com/code/app-nous/blob/main/src/functions/jira.ts"
    click GmailInt "https://github.com/code/app-nous/blob/main/src/functions/email/gmail.ts"
    click Firestore "https://github.com/code/app-nous/tree/main/src/modules/firestore/"
    click MemoryDB "https://github.com/code/app-nous/tree/main/src/modules/memory/"
    click PGCache "https://github.com/code/app-nous/blob/main/src/cache/pgFunctionCache.ts"
    click FastifyTrace "https://github.com/code/app-nous/tree/main/src/fastify/trace-init/"
    click Tracer "https://github.com/code/app-nous/blob/main/src/o11y/trace.ts"
    click Logger "https://github.com/code/app-nous/blob/main/src/o11y/logger.ts"

    %% Styles
    classDef frontend fill:#DAE8FC,stroke:#6C8EBF,color:#000
    classDef backend fill:#E1D5E7,stroke:#9673A6,color:#000
    classDef engine fill:#FFF2CC,stroke:#D6B656,color:#000
    classDef plugin fill:#F8CECC,stroke:#B85450,color:#000
    classDef persistence fill:#D5E8D4,stroke:#82B366,color:#000
    classDef external fill:#F5F5F5,stroke:#999999,color:#000
    classDef o11y fill:#FFE6CC,stroke:#E69138,color:#000
```
