# akshaya-csbs/krylo architecture

> Architecture diagram of the GitHub repository akshaya-csbs/krylo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshaya-csbs/krylo
- Repository: https://github.com/akshaya-csbs/krylo

## Overview

#### Purpose and Entry Points
This is a full-stack brand intelligence and campaign-analysis product. The backend exposes a modular API for authentication, brand onboarding, asset ingestion, identity analysis, trends, validation, optimization, campaign management, and an AI copilot. The frontend provides an onboarding flow and dashboard views for those capabilities.

- Backend application entry: `backend/app/main.py`
- API aggregation: `backend/app/api/router.py`
- Frontend entry/layout: `frontend/src/app/page.tsx`, `frontend/src/app/layout.tsx`

#### API and Request Boundary
FastAPI-style route modules separate HTTP concerns from domain services and schemas. Route-level dependency handling likely centralizes authentication/database access before services execute domain operations.

- API routes: `backend/app/api/auth.py`, `backend/app/api/brands.py`, `backend/app/api/copilot.py`
- Shared dependencies: `backend/app/api/deps.py`
- Request/response contracts: `backend/app/schemas/auth.py`, `backend/app/schemas/brand.py`, `backend/app/schemas/copilot.py`

#### Domain Persistence Layer
The backend models the product around users, brands, brand identity, campaigns, trends, validations, optimizations, and asynchronous jobs. Database wiring is isolated from domain models, enabling service-layer orchestration over persisted entities.

- Database setup: `backend/app/database.py`
- Core entities: `backend/app/models/brand.py`, `backend/app/models/campaign.py`, `backend/app/models/user.py`
- Analysis entities: `backend/app/models/identity.py`, `backend/app/models/trend.py`, `backend/app/models/validation.py`

#### Service-Oriented Business Workflows
Services represent the primary control-flow boundary between API endpoints and models/external integrations. Brand and identity workflows likely feed later campaign, validation, trend, and optimization workflows; job handling supports work that may not complete within a single request.

- Brand/identity workflows: `backend/app/services/brand_service.py`, `backend/app/services/identity_service.py`
- Campaign and optimization workflows: `backend/app/services/campaign_service.py`, `backend/app/services/optimization_service.py`
- Job and dashboard aggregation: `backend/app/services/job_service.py`, `backend/app/services/dashboard_service.py`

#### AI Analysis Pipeline
AI capabilities are encapsulated behind analyzers and an orchestration service rather than embedded in routes. The pipeline supports both Groq-backed language analysis and multimodal analysis, with outputs exposed through identity, validation, optimization, and copilot-facing APIs.

- AI integration: `backend/app/ai/groq_analyzer.py`, `backend/app/ai/multimodal_analyzer.py`
- Orchestration boundary: `backend/app/services/ai_analysis_service.py`
- Consumer APIs: `backend/app/api/identity.py`, `backend/app/api/validation.py`, `backend/app/api/optimization.py`

#### Asset Storage and Runtime Infrastructure
The backend has environment-driven configuration, relational persistence, local brand asset storage, and security utilities. Uploaded or ingested brand materials are stored separately from application code and can be analyzed by the AI pipeline.

- Configuration and environment contract: `backend/app/config.py`, `backend/.env.example`
- Local asset storage: `backend/storage/brands`
- Security/storage utilities: `backend/app/utils/security.py`, `backend/app/utils/storage.py`
- Python runtime dependencies: `backend/requirements.txt`

#### Frontend Dashboard Composition
The Next.js frontend uses a dashboard client shell with feature-specific views. The UI maps directly to backend product domains: asset ingestion, brand identity, layered AI analysis, trends, validation, impact simulation/optimization, settings, and copilot interaction.

- Dashboard coordinator: `frontend/src/components/dashboard/DashboardClient.tsx`
- Analysis views: `frontend/src/components/dashboard/BrandIdentityView.tsx`, `frontend/src/components/dashboard/LayeredAnalysisView.tsx`, `frontend/src/components/dashboard/ValidationView.tsx`
- Decision-support views: `frontend/src/components/dashboard/TrendAnalyticsView.tsx`, `frontend/src/components/dashboard/ImpactSimulationView.tsx`, `frontend/src/components/dashboard/CopilotView.tsx`

Main entry points: [`backend/app/api/brands.py`](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/brands.py) (Product routes), [`backend/app/services/brand_service.py`](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/brand_service.py) (Brand & campaign workflows), [`frontend/src/components/dashboard/DashboardClient.tsx`](https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/DashboardClient.tsx) (Dashboard shell), [`backend/app/services/ai_analysis_service.py`](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/ai_analysis_service.py) (AI analysis orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_entry["App entry &amp; layout<br/>Next.js app<br/>[page.tsx]"]
  node_dashboard["Dashboard shell<br/>dashboard coordinator"]
  node_analysis_views["Analysis views<br/>dashboard views"]
  node_decision_views["Decision-support views<br/>dashboard views"]
end

subgraph group_api["Backend API"]
  node_backend_app["Backend application<br/>FastAPI entry<br/>[main.py]"]
  node_api_router["API router<br/>route aggregator<br/>[router.py]"]
  node_route_modules["Product routes<br/>HTTP routes<br/>[brands.py]"]
  node_api_dependencies["Shared dependencies<br/>request dependencies<br/>[deps.py]"]
  node_schemas["API contracts<br/>request/response schemas<br/>[brand.py]"]
end

subgraph group_services["Workflows"]
  node_domain_workflows["Brand &amp; campaign workflows<br/>domain services<br/>[brand_service.py]"]
  node_job_dashboard["Jobs &amp; dashboard aggregation<br/>application services<br/>[job_service.py]"]
end

subgraph group_ai["AI Pipeline"]
  node_ai_service["AI analysis orchestration<br/>analysis service"]
  node_ai_analyzers{{"Groq &amp; multimodal analyzers<br/>AI integrations<br/>[groq_analyzer.py]"}}
end

subgraph group_data["Data &amp; Storage"]
  node_database[("Database setup<br/>relational persistence<br/>[database.py]")]
  node_core_models["Core entities<br/>ORM models<br/>[brand.py]"]
  node_analysis_models["Analysis entities<br/>ORM models<br/>[identity.py]"]
  node_asset_storage[("Brand asset storage<br/>local storage")]
  node_storage_utils["Storage &amp; security utilities<br/>infrastructure utilities<br/>[storage.py]"]
end

node_frontend_entry -->|"renders"| node_dashboard
node_dashboard -->|"hosts"| node_analysis_views
node_dashboard -->|"hosts"| node_decision_views
node_dashboard -->|"API requests"| node_api_router
node_backend_app -->|"mounts"| node_api_router
node_api_router -->|"dispatches"| node_route_modules
node_route_modules -->|"uses"| node_api_dependencies
node_route_modules -->|"validates with"| node_schemas
node_route_modules -->|"invokes"| node_domain_workflows
node_route_modules -->|"analysis endpoints"| node_ai_service
node_domain_workflows -->|"schedules &amp; aggregates"| node_job_dashboard
node_domain_workflows -->|"manages"| node_core_models
node_domain_workflows -->|"produces"| node_analysis_models
node_domain_workflows -->|"ingests assets"| node_asset_storage
node_job_dashboard -->|"persists jobs"| node_database
node_ai_service -->|"orchestrates"| node_ai_analyzers
node_ai_service -->|"stores results"| node_analysis_models
node_ai_service -->|"analyzes materials"| node_asset_storage
node_storage_utils -->|"reads &amp; writes"| node_asset_storage
node_core_models -->|"mapped to"| node_database
node_analysis_models -->|"mapped to"| node_database

click node_frontend_entry "https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/app/page.tsx"
click node_dashboard "https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/DashboardClient.tsx"
click node_analysis_views "https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/BrandIdentityView.tsx"
click node_decision_views "https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/TrendAnalyticsView.tsx"
click node_backend_app "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/main.py"
click node_api_router "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/router.py"
click node_route_modules "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/brands.py"
click node_api_dependencies "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/deps.py"
click node_schemas "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/schemas/brand.py"
click node_domain_workflows "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/brand_service.py"
click node_job_dashboard "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/job_service.py"
click node_ai_service "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/ai_analysis_service.py"
click node_ai_analyzers "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/ai/groq_analyzer.py"
click node_database "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/database.py"
click node_core_models "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/models/brand.py"
click node_analysis_models "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/models/identity.py"
click node_asset_storage "https://github.com/akshaya-csbs/krylo/tree/main/backend/storage/brands"
click node_storage_utils "https://github.com/akshaya-csbs/krylo/blob/main/backend/app/utils/storage.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_entry,node_dashboard,node_analysis_views,node_decision_views toneBlue
class node_backend_app,node_api_router,node_route_modules,node_api_dependencies,node_schemas toneAmber
class node_domain_workflows,node_job_dashboard toneMint
class node_ai_service,node_ai_analyzers toneRose
class node_database,node_core_models,node_analysis_models,node_asset_storage,node_storage_utils toneIndigo
```

## Components

### Frontend

- [App entry & layout](https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/app/page.tsx): Next.js app · `frontend/src/app/page.tsx`
- [Dashboard shell](https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/DashboardClient.tsx): dashboard coordinator · Composes product-domain views. · `frontend/src/components/dashboard/DashboardClient.tsx`
- [Analysis views](https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/BrandIdentityView.tsx): dashboard views · Identity, layered analysis, and validation UI. · `frontend/src/components/dashboard/BrandIdentityView.tsx`
- [Decision-support views](https://github.com/akshaya-csbs/krylo/blob/main/frontend/src/components/dashboard/TrendAnalyticsView.tsx): dashboard views · Trends, impact simulation, and copilot UI. · `frontend/src/components/dashboard/TrendAnalyticsView.tsx`

### Backend API

- [Backend application](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/main.py): FastAPI entry · `backend/app/main.py`
- [API router](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/router.py): route aggregator · `backend/app/api/router.py`
- [Product routes](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/brands.py): HTTP routes · Auth, brands, and copilot request boundary. · `backend/app/api/brands.py`
- [Shared dependencies](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/api/deps.py): request dependencies · Provides authentication and database access. · `backend/app/api/deps.py`
- [API contracts](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/schemas/brand.py): request/response schemas · `backend/app/schemas/brand.py`

### Workflows

- [Brand & campaign workflows](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/brand_service.py): domain services · Orchestrates brand identity, campaign, and optimization work. · `backend/app/services/brand_service.py`
- [Jobs & dashboard aggregation](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/job_service.py): application services · Coordinates asynchronous work and dashboard data. · `backend/app/services/job_service.py`

### AI Pipeline

- [AI analysis orchestration](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/services/ai_analysis_service.py): analysis service · Makes AI results available to identity, validation, optimization, and copilot flows. · `backend/app/services/ai_analysis_service.py`
- [Groq & multimodal analyzers](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/ai/groq_analyzer.py): AI integrations · `backend/app/ai/groq_analyzer.py`

### Data & Storage

- [Database setup](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/database.py): relational persistence · `backend/app/database.py`
- [Core entities](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/models/brand.py): ORM models · Users, brands, and campaigns. · `backend/app/models/brand.py`
- [Analysis entities](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/models/identity.py): ORM models · Identity, trend, and validation records. · `backend/app/models/identity.py`
- [Brand asset storage](https://github.com/akshaya-csbs/krylo/tree/main/backend/storage/brands): local storage · Stores uploaded and ingested brand materials. · `backend/storage/brands`
- [Storage & security utilities](https://github.com/akshaya-csbs/krylo/blob/main/backend/app/utils/storage.py): infrastructure utilities · `backend/app/utils/storage.py`

## Connections

- App entry & layout → Dashboard shell: renders
- Dashboard shell → Analysis views: hosts
- Dashboard shell → Decision-support views: hosts
- Dashboard shell → API router: API requests
- Backend application → API router: mounts
- API router → Product routes: dispatches
- Product routes → Shared dependencies: uses
- Product routes → API contracts: validates with
- Product routes → Brand & campaign workflows: invokes
- Product routes → AI analysis orchestration: analysis endpoints
- Brand & campaign workflows → Jobs & dashboard aggregation: schedules & aggregates
- Brand & campaign workflows → Core entities: manages
- Brand & campaign workflows → Analysis entities: produces
- Brand & campaign workflows → Brand asset storage: ingests assets
- Jobs & dashboard aggregation → Database setup: persists jobs
- AI analysis orchestration → Groq & multimodal analyzers: orchestrates
- AI analysis orchestration → Analysis entities: stores results
- AI analysis orchestration → Brand asset storage: analyzes materials
- Storage & security utilities → Brand asset storage: reads & writes
- Core entities → Database setup: mapped to
- Analysis entities → Database setup: mapped to