# daksh22ai/logam-os architecture

> Architecture diagram of the GitHub repository daksh22ai/logam-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daksh22ai/logam-os
- Repository: https://github.com/daksh22ai/logam-os

## Overview

1. **This repo is split into two independently running applications.**  
   The `frontend/` folder is a Next.js 16.2 app for the user-facing dashboard and supporting UI.  
   The `backend/` folder is a FastAPI service dedicated to AI chat/generation.

2. **The frontend is the main orchestration layer for the product UI.**  
   It uses the Next.js App Router under `src/app/` with distinct surfaces for:
   - `dashboard/` and nested brand/channel views
   - `chat/`
   - `welcome/`
   - landing/home pages
   This suggests a multi-tenant agency workspace centered around brands/clients and channel-specific views.

3. **Frontend UI is organized by domain, not by generic component type.**  
   Components are grouped into `alerts`, `chat`, `creative`, `finance`, `landing`, `onboarding`, `reporting`, and `shell`.  
   That implies the main architectural boundary in the UI is feature area, with shared layout chrome in `shell/` and reusable primitives in `ui/`.

4. **The frontend has a clear client-data boundary separate from AI/chat.**  
   `src/app/api/clients/...` contains Next route handlers for client and metrics endpoints, while `src/lib/db.ts`, `prisma/schema.prisma`, and `prisma/seed.ts` indicate a Prisma-backed database layer.  
   In practice, the frontend likely owns its own application data model for clients, metrics, and dashboard state.

5. **State management in the frontend is lightweight and local.**  
   `src/stores/ui.ts` uses Zustand for UI state, which fits the layout-centric nature of the app: sidebar/rail visibility, panel state, or similar interaction state rather than heavy global domain logic.

6. **The backend is a focused AI service, not a full product server.**  
   FastAPI exposes a small API surface:
   - `GET /health`
   - `POST /api/chat`
   - `POST /api/chat/stream`
   This makes the backend a dedicated generation layer for chat responses, including streaming output.

7. **The backend follows a layered design.**  
   The file layout separates:
   - `routes/` for HTTP handlers
   - `services/` for orchestration logic
   - `chatbot/` for agent/chain/prompt construction
   - `db/` for persistence access
   - `models/` for schemas and database models
   - `config.py` and `utils/logger.py` for environment and observability  
   This is a standard API → service → domain/AI → persistence flow.

8. **AI generation is built around LangChain and Groq.**  
   The README explicitly calls out LangChain plus the Groq API, and the `backend/app/chatbot/` folder reinforces that the model interaction is encapsulated as an agent/chain with prompt definitions.  
   The key architectural boundary here is between request handling and model orchestration.

9. **Backend persistence appears to use a local SQLite database.**  
   The presence of `backend/logam_os.db` alongside `db/database.py`, `crud.py`, and `models.py` implies a lightweight relational store for backend state.  
   This is separate from the frontend’s Prisma-backed data layer, so the system has two data stores with different responsibilities.

10. **The main end-to-end flow is: UI request → frontend API/data layer → backend AI service.**  
   Dashboard pages and the chat page render product workflows, while chat-related components likely call `src/lib/api.ts`, which in turn reaches the FastAPI service for AI responses.  
   Client/metrics dashboard data is handled inside the Next app through its own API routes and database layer.

11. **The app shell is designed as an agency command center.**  
   `components/shell/` includes `Sidebar`, `Rail`, `MainHeader`, and `AIPanel`, which indicates a persistent workspace layout with an always-available assistant panel alongside the main content area.

12. **The product surface is strongly dashboard-oriented and multi-tenant.**  
   The route structure uses `[brandId]` and `[channel]` segments, which is a strong signal that the system organizes work around client brands and marketing channels rather than around a single-user consumer model.

13. **Infrastructure/runtime split matters for the architecture diagram.**  
   The frontend runs on Node/Next.js, with Prisma as its DB access layer.  
   The backend runs on Python/FastAPI with Uvicorn, LangChain, and Groq.  
   These are separate deployables with different runtimes and different data responsibilities.

14. **Overall, the system is a two-tier product architecture.**  
   The Next.js app owns presentation, dashboard workflows, and client data APIs.  
   The FastAPI app owns AI chat generation and streaming.  
   Shared concerns are minimal, and the boundary between the two is the chat/AI integration path.

Main entry points: [`frontend/src/app`](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app) (Next app), [`backend/app/services/chat_service.py`](https://github.com/daksh22ai/logam-os/blob/main/backend/app/services/chat_service.py) (Chat service), [`frontend/src/components/shell`](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components/shell) (App shell), [`backend/app/main.py`](https://github.com/daksh22ai/logam-os/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next app<br/>Next.js app"]
  node_frontend_dashboard["Dashboard<br/>route surface"]
  node_frontend_chat["Chat page<br/>route surface<br/>[page.tsx]"]
  node_frontend_api_clients["Client API<br/>route handlers"]
  node_frontend_shell["App shell<br/>layout chrome"]
  node_frontend_domain_components["Domain UI<br/>feature components"]
  node_frontend_ui["UI primitives<br/>shared UI"]
  node_frontend_lib_api["Frontend API client<br/>integration layer<br/>[api.ts]"]
  node_frontend_lib_db[("Prisma DB<br/>data access<br/>[db.ts]")]
  node_frontend_prisma["Prisma schema<br/>[schema.prisma]"]
  node_frontend_store["UI store<br/>state store<br/>[ui.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>API service<br/>[main.py]"]
  node_backend_routes["HTTP routes<br/>route layer"]
  node_backend_service["Chat service<br/>service layer<br/>[chat_service.py]"]
  node_backend_chatbot["AI chain<br/>agent layer"]
  node_backend_db[("SQLite data<br/>persistence")]
  node_backend_models["Schemas<br/>models"]
  node_backend_config["Config<br/>[config.py]"]
end

node_frontend_app -->|"renders"| node_frontend_dashboard
node_frontend_app -->|"renders"| node_frontend_chat
node_frontend_app -->|"serves"| node_frontend_api_clients
node_frontend_app -->|"wraps"| node_frontend_shell
node_frontend_shell -->|"uses"| node_frontend_domain_components
node_frontend_domain_components -->|"builds on"| node_frontend_ui
node_frontend_chat -->|"calls"| node_frontend_lib_api
node_frontend_dashboard -->|"reads/writes"| node_frontend_lib_db
node_frontend_lib_db -->|"maps to"| node_frontend_prisma
node_frontend_shell -->|"controls"| node_frontend_store
node_frontend_lib_api -->|"requests"| node_backend_main
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_service
node_backend_service -->|"orchestrates"| node_backend_chatbot
node_backend_service -->|"persists"| node_backend_db
node_backend_service -->|"uses"| node_backend_models
node_backend_main -->|"configures"| node_backend_config
node_backend_db -->|"stores"| node_backend_models

click node_frontend_app "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app"
click node_frontend_dashboard "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app/(dashboard)"
click node_frontend_chat "https://github.com/daksh22ai/logam-os/blob/main/frontend/src/app/chat/page.tsx"
click node_frontend_api_clients "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app/api/clients"
click node_frontend_shell "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components/shell"
click node_frontend_domain_components "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components"
click node_frontend_ui "https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components/ui"
click node_frontend_lib_api "https://github.com/daksh22ai/logam-os/blob/main/frontend/src/lib/api.ts"
click node_frontend_lib_db "https://github.com/daksh22ai/logam-os/blob/main/frontend/src/lib/db.ts"
click node_frontend_prisma "https://github.com/daksh22ai/logam-os/blob/main/frontend/prisma/schema.prisma"
click node_frontend_store "https://github.com/daksh22ai/logam-os/blob/main/frontend/src/stores/ui.ts"
click node_backend_main "https://github.com/daksh22ai/logam-os/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/daksh22ai/logam-os/tree/main/backend/app/routes"
click node_backend_service "https://github.com/daksh22ai/logam-os/blob/main/backend/app/services/chat_service.py"
click node_backend_chatbot "https://github.com/daksh22ai/logam-os/tree/main/backend/app/chatbot"
click node_backend_db "https://github.com/daksh22ai/logam-os/tree/main/backend/app/db"
click node_backend_models "https://github.com/daksh22ai/logam-os/tree/main/backend/app/models"
click node_backend_config "https://github.com/daksh22ai/logam-os/blob/main/backend/app/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_dashboard,node_frontend_chat,node_frontend_api_clients,node_frontend_shell,node_frontend_domain_components,node_frontend_ui,node_frontend_lib_api,node_frontend_lib_db,node_frontend_prisma,node_frontend_store toneBlue
class node_backend_main,node_backend_routes,node_backend_service,node_backend_chatbot,node_backend_db,node_backend_models,node_backend_config toneAmber
```

## Components

### Frontend

Next.js app for dashboard UI, client data, and chat entrypoints.

- [Next app](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app): Next.js app · App Router surfaces for dashboard, chat, welcome, and landing pages. · `frontend/src/app`
- [Dashboard](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app/(dashboard)): route surface · Multi-tenant workspace routes for brands and channels. · `frontend/src/app/(dashboard)`
- [Chat page](https://github.com/daksh22ai/logam-os/blob/main/frontend/src/app/chat/page.tsx): route surface · User-facing chat entrypoint in the frontend. · `frontend/src/app/chat/page.tsx`
- [Client API](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/app/api/clients): route handlers · Next route handlers for client and metrics data. · `frontend/src/app/api/clients`
- [App shell](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components/shell): layout chrome · Persistent workspace chrome with sidebar, rail, header, and AI panel. · `frontend/src/components/shell`
- [Domain UI](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components): feature components · Feature-oriented UI for alerts, chat, creative, finance, landing, onboarding, and reporting. · `frontend/src/components`
- [UI primitives](https://github.com/daksh22ai/logam-os/tree/main/frontend/src/components/ui): shared UI · Reusable presentation primitives and empty/loading states. · `frontend/src/components/ui`
- [Frontend API client](https://github.com/daksh22ai/logam-os/blob/main/frontend/src/lib/api.ts): integration layer · Client-side integration that calls external services, including AI chat. · `frontend/src/lib/api.ts`
- [Prisma DB](https://github.com/daksh22ai/logam-os/blob/main/frontend/src/lib/db.ts): data access · Frontend database connection and application data access. · `frontend/src/lib/db.ts`
- [Prisma schema](https://github.com/daksh22ai/logam-os/blob/main/frontend/prisma/schema.prisma): schema · Frontend data model and seed definitions. · `frontend/prisma/schema.prisma`
- [UI store](https://github.com/daksh22ai/logam-os/blob/main/frontend/src/stores/ui.ts): state store · Local Zustand state for shell and interaction state. · `frontend/src/stores/ui.ts`

### Backend

FastAPI service for AI chat generation and streaming.

- [FastAPI app](https://github.com/daksh22ai/logam-os/blob/main/backend/app/main.py): API service · Python service entrypoint exposing chat and health routes. · `backend/app/main.py`
- [HTTP routes](https://github.com/daksh22ai/logam-os/tree/main/backend/app/routes): route layer · Health and chat endpoints for the AI service. · `backend/app/routes`
- [Chat service](https://github.com/daksh22ai/logam-os/blob/main/backend/app/services/chat_service.py): service layer · Orchestrates chat request handling and response assembly. · `backend/app/services/chat_service.py`
- [AI chain](https://github.com/daksh22ai/logam-os/tree/main/backend/app/chatbot): agent layer · LangChain/Groq prompt, agent, and chain construction. · `backend/app/chatbot`
- [SQLite data](https://github.com/daksh22ai/logam-os/tree/main/backend/app/db): persistence · Backend database access and local relational storage. · `backend/app/db`
- [Schemas](https://github.com/daksh22ai/logam-os/tree/main/backend/app/models): models · Request/response and database models for the backend. · `backend/app/models`
- [Config](https://github.com/daksh22ai/logam-os/blob/main/backend/app/config.py): runtime config · Environment and logging configuration for the AI service. · `backend/app/config.py`

## Connections

- Next app → Dashboard: renders · The App Router hosts the dashboard workspace surfaces.
- Next app → Chat page: renders · The App Router provides the chat page.
- Next app → Client API: serves · Route handlers expose client and metrics APIs.
- Next app → App shell: wraps · Global layout composes the persistent shell.
- App shell → Domain UI: uses · Shell integrates feature-specific UI areas.
- Domain UI → UI primitives: builds on · Feature components reuse shared primitives.
- Chat page → Frontend API client: calls · Chat UI sends requests through the frontend API layer.
- Dashboard → Prisma DB: reads/writes · Dashboard workflows use the Prisma-backed data layer.
- Prisma DB → Prisma schema: maps to · Database access is defined by the Prisma schema.
- App shell → UI store: controls · Local UI state drives shell interactions.
- Frontend API client → FastAPI app: requests · Frontend chat integration reaches the FastAPI service.
- FastAPI app → HTTP routes: mounts · The FastAPI app exposes route handlers.
- HTTP routes → Chat service: delegates · HTTP handlers pass work to the chat service.
- Chat service → AI chain: orchestrates · Service logic constructs and runs the AI chain.
- Chat service → SQLite data: persists · Chat service can read/write backend state.
- Chat service → Schemas: uses · Service layer depends on request and domain models.
- FastAPI app → Config: configures · Runtime behavior is driven by config and logging.
- SQLite data → Schemas: stores · Database layer uses backend model definitions.
