# jesgoy/argos architecture

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

- Interactive diagram: https://gitdiagram.com/jesgoy/argos
- Repository: https://github.com/jesgoy/argos

## Overview

1. **Overall shape**
   This is a Next.js 16 App Router application built as a cleanly layered inventory/POS system. The codebase is split into presentation (`src/app`), application (`src/core/application`), domain (`src/core/domain`), and infrastructure (`src/infra`) layers, with PostgreSQL accessed through Drizzle ORM.

2. **Primary business subsystems**
   The repository centers on four business areas: authentication, product catalog management, sales/stock processing, and an AI assistant with conversation history. Each area has its own routes, use cases, repository ports, and infrastructure implementations, which keeps the modules mostly independent.

3. **Presentation layer and route boundaries**
   `src/app` contains the user-facing routes organized by feature:
   - `(auth)` for login/register
   - `(dashboard)` for protected screens like products, sales, POS, AI assistant, and logout
   - `api/conversations` for conversation-related API access  
   Pages are mostly server components, while forms and interactive panels are client components. Mutations are handled through feature-specific server actions alongside the pages.

4. **Authentication and session flow**
   Authentication is implemented with `LoginUser`, `RegisterUser`, `GetSession`, and `AuthorizeRole` use cases. The infrastructure layer provides `HashServiceBcrypt` for password hashing and `JWTSessionService` for session issuance/verification. `src/app/lib/auth.ts` likely bridges the app layer with session checks used by dashboard routes and logout.

5. **Product management flow**
   Product CRUD is a full vertical slice:
   - UI: `products/page.tsx`, create/edit forms, and list components
   - Actions: `src/app/(dashboard)/products/actions.ts`
   - Use cases: create, read, update, delete
   - Repository port: `ProductRepository`
   - Infrastructure: `ProductRepositoryDrizzle`
   - Validation: `src/infra/validation/product.ts`  
   This slice enforces SKU rules, stock thresholds, and product-specific domain errors before data reaches the database.

6. **Sales, POS, and stock control**
   The POS and sales features share a sales-oriented application boundary. Use cases such as `ProcessSale`, `CancelSale`, `AdjustStock`, `GetSalesReport`, and `GetProductStock` coordinate sales records, sale items, stock transactions, and product inventory state. The data model includes `Sale`, `SaleItem`, and `StockTransaction`, indicating stock is tracked as transactional movement rather than only a mutable counter.

7. **AI assistant and conversation persistence**
   The AI assistant is a separate subsystem built around `ProcessAICommand` and conversation/message persistence. `ChatInterface` and `ChatPanel` provide the UI, `src/app/api/conversations/route.ts` exposes conversation operations, and `VercelAIService` is the external AI adapter. Conversation history is stored through `ConversationRepositoryDrizzle` and `MessageRepositoryDrizzle`, with dedicated use cases for create, delete, lookup, and history retrieval.

8. **Application layer contracts**
   `src/core/application/ports` defines the abstractions the use cases depend on: repositories for users, products, sales, customers, conversations, messages, sale items, and stock transactions, plus service ports for hashing, sessions, and AI. This is the main dependency inversion boundary: business logic talks to interfaces, while infrastructure provides the concrete implementations.

9. **Domain model**
   `src/core/domain/entities` contains the business objects: `User`, `Product`, `Sale`, `SaleItem`, `StockTransaction`, `Conversation`, `Message`, `Customer`, and `AIIntent`. Domain constants and error modules encode business rules and failure cases, keeping validation and invariants out of the UI and database adapters.

10. **Infrastructure and persistence**
   `src/infra/db` holds the Drizzle client and schema, while `drizzle/` contains the generated SQL migrations and snapshots. Repository adapters in `src/infra/repositories` translate use-case requests into database operations. `src/infra/validation` provides Zod schemas for request validation before invoking use cases. This layer is the bridge to PostgreSQL on Neon, as described in the README.

11. **Dependency wiring**
   `src/infra/container` groups factories for assembling feature-level dependencies for AI, auth, products, and sales. These containers are the composition points where application use cases are connected to repository and service implementations, keeping the rest of the app from importing concrete infra classes directly.

12. **Operational and maintenance pieces**
   The repo includes a database schema/migration workflow through Drizzle CLI scripts and a maintenance script at `scripts/update-user-role.ts`, suggesting some administrative operations happen outside the main UI. The root config files indicate TypeScript strictness, ESLint, and Next.js build/runtime setup as the main tooling around the architecture.

Main entry points: [`src/core/application/ports/ProductRepository.ts`](https://github.com/jesgoy/argos/blob/main/src/core/application/ports/ProductRepository.ts) (Ports), [`src/app/(dashboard)/layout.tsx`](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/layout.tsx) (Dashboard), [`src/infra/container/auth.ts`](https://github.com/jesgoy/argos/blob/main/src/infra/container/auth.ts) (Containers), [`src/infra/validation/auth.ts`](https://github.com/jesgoy/argos/blob/main/src/infra/validation/auth.ts) (Validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_root["App shell<br/>Next.js app<br/>[layout.tsx]"]
  node_auth_routes["Auth routes<br/>route group<br/>[page.tsx]"]
  node_dashboard_routes["Dashboard<br/>protected routes<br/>[layout.tsx]"]
  node_products_ui["Products UI<br/>feature UI<br/>[page.tsx]"]
  node_sales_ui["Sales UI<br/>feature UI<br/>[page.tsx]"]
  node_pos_ui["POS UI<br/>feature UI<br/>[page.tsx]"]
  node_ai_ui["AI assistant<br/>feature UI<br/>[page.tsx]"]
end

subgraph group_application["Application"]
  node_auth_usecases["Auth use cases<br/>application service<br/>[LoginUser.ts]"]
  node_product_usecases["Product use cases<br/>application service<br/>[CreateProduct.ts]"]
  node_sales_usecases["Sales use cases<br/>application service<br/>[ProcessSale.ts]"]
  node_conversation_usecases["Conversation use cases<br/>application service"]
  node_ai_usecase["AI command<br/>application service"]
  node_ports["Ports<br/>boundary"]
end

subgraph group_domain["Domain"]
  node_domain_models["Domain model<br/>entities and rules<br/>[Product.ts]"]
end

subgraph group_infrastructure["Infrastructure"]
  node_db_layer["DB layer<br/>persistence<br/>[client.ts]"]
  node_repo_adapters["Repositories<br/>adapters"]
  node_security_services["Security services<br/>adapters"]
  node_ai_adapter["AI adapter<br/>external service<br/>[VercelAIService.ts]"]
  node_containers["Containers<br/>composition root<br/>[auth.ts]"]
  node_validation["Validation<br/>[auth.ts]"]
end

node_app_root -->|"routes"| node_auth_routes
node_app_root -->|"routes"| node_dashboard_routes
node_dashboard_routes -->|"feature"| node_products_ui
node_dashboard_routes -->|"feature"| node_sales_ui
node_dashboard_routes -->|"feature"| node_pos_ui
node_dashboard_routes -->|"feature"| node_ai_ui
node_auth_routes -->|"invoke"| node_auth_usecases
node_products_ui -->|"invoke"| node_product_usecases
node_sales_ui -->|"invoke"| node_sales_usecases
node_pos_ui -->|"invoke"| node_sales_usecases
node_ai_ui -->|"invoke"| node_ai_usecase
node_ai_ui -->|"invoke"| node_conversation_usecases
node_auth_usecases -->|"depends on"| node_ports
node_product_usecases -->|"depends on"| node_ports
node_sales_usecases -->|"depends on"| node_ports
node_conversation_usecases -->|"depends on"| node_ports
node_ai_usecase -->|"depends on"| node_ports
node_ports -->|"expresses"| node_domain_models
node_repo_adapters -->|"persists to"| node_db_layer
node_repo_adapters -->|"maps"| node_domain_models
node_security_services -->|"implements"| node_auth_usecases
node_ai_adapter -->|"implements"| node_ai_usecase
node_containers -->|"wires"| node_auth_usecases
node_containers -->|"wires"| node_product_usecases
node_containers -->|"wires"| node_sales_usecases
node_containers -->|"wires"| node_ai_usecase
node_validation -->|"guards"| node_auth_routes
node_validation -->|"guards"| node_products_ui
node_validation -->|"guards"| node_sales_ui
node_validation -->|"guards"| node_ai_ui

click node_app_root "https://github.com/jesgoy/argos/blob/main/src/app/layout.tsx"
click node_auth_routes "https://github.com/jesgoy/argos/blob/main/src/app/(auth)/login/page.tsx"
click node_dashboard_routes "https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/layout.tsx"
click node_products_ui "https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/products/page.tsx"
click node_sales_ui "https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/sales/page.tsx"
click node_pos_ui "https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/pos/page.tsx"
click node_ai_ui "https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/ai-assistant/page.tsx"
click node_auth_usecases "https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/auth/LoginUser.ts"
click node_product_usecases "https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/products/CreateProduct.ts"
click node_sales_usecases "https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/sales/ProcessSale.ts"
click node_conversation_usecases "https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/conversations/CreateConversation.ts"
click node_ai_usecase "https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/ai/ProcessAICommand.ts"
click node_ports "https://github.com/jesgoy/argos/blob/main/src/core/application/ports/ProductRepository.ts"
click node_domain_models "https://github.com/jesgoy/argos/blob/main/src/core/domain/entities/Product.ts"
click node_db_layer "https://github.com/jesgoy/argos/blob/main/src/infra/db/client.ts"
click node_repo_adapters "https://github.com/jesgoy/argos/blob/main/src/infra/repositories/ProductRepositoryDrizzle.ts"
click node_security_services "https://github.com/jesgoy/argos/blob/main/src/infra/security/HashServiceBcrypt.ts"
click node_ai_adapter "https://github.com/jesgoy/argos/blob/main/src/infra/ai/VercelAIService.ts"
click node_containers "https://github.com/jesgoy/argos/blob/main/src/infra/container/auth.ts"
click node_validation "https://github.com/jesgoy/argos/blob/main/src/infra/validation/auth.ts"

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_app_root,node_auth_routes,node_dashboard_routes,node_products_ui,node_sales_ui,node_pos_ui,node_ai_ui toneBlue
class node_auth_usecases,node_product_usecases,node_sales_usecases,node_conversation_usecases,node_ai_usecase,node_ports toneAmber
class node_domain_models toneMint
class node_db_layer,node_repo_adapters,node_security_services,node_ai_adapter,node_containers,node_validation toneRose
```

## Components

### Presentation

Next.js App Router routes, pages, components, and server actions

- [App shell](https://github.com/jesgoy/argos/blob/main/src/app/layout.tsx): Next.js app · Root layout, landing page, and shared app chrome · `src/app/layout.tsx`
- [Auth routes](https://github.com/jesgoy/argos/blob/main/src/app/(auth)/login/page.tsx): route group · Login and registration screens with server actions · `src/app/(auth)/login/page.tsx`
- [Dashboard](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/layout.tsx): protected routes · Authenticated workspace for products, sales, POS, AI, and logout · `src/app/(dashboard)/layout.tsx`
- [Products UI](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/products/page.tsx): feature UI · Product list, create/edit forms, and product actions · `src/app/(dashboard)/products/page.tsx`
- [Sales UI](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/sales/page.tsx): feature UI · Sales list and sales-related actions · `src/app/(dashboard)/sales/page.tsx`
- [POS UI](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/pos/page.tsx): feature UI · Point-of-sale interface and checkout actions · `src/app/(dashboard)/pos/page.tsx`
- [AI assistant](https://github.com/jesgoy/argos/blob/main/src/app/(dashboard)/ai-assistant/page.tsx): feature UI · Chat interface plus conversation API entry points · `src/app/(dashboard)/ai-assistant/page.tsx`

### Application

Use cases and ports that coordinate business workflows

- [Auth use cases](https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/auth/LoginUser.ts): application service · Login, registration, session lookup, and role authorization · `src/core/application/usecases/auth/LoginUser.ts`
- [Product use cases](https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/products/CreateProduct.ts): application service · Create, read, update, and delete products · `src/core/application/usecases/products/CreateProduct.ts`
- [Sales use cases](https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/sales/ProcessSale.ts): application service · Process sales, cancel sales, adjust stock, and reporting · `src/core/application/usecases/sales/ProcessSale.ts`
- [Conversation use cases](https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/conversations/CreateConversation.ts): application service · Create, fetch, list history, and delete conversations and messages · `src/core/application/usecases/conversations/CreateConversation.ts`
- [AI command](https://github.com/jesgoy/argos/blob/main/src/core/application/usecases/ai/ProcessAICommand.ts): application service · Interprets chat intent and coordinates AI responses · `src/core/application/usecases/ai/ProcessAICommand.ts`
- [Ports](https://github.com/jesgoy/argos/blob/main/src/core/application/ports/ProductRepository.ts): boundary · Repository and service interfaces used by application code · `src/core/application/ports/ProductRepository.ts`

### Domain

Core business entities, constants, and rule errors

- [Domain model](https://github.com/jesgoy/argos/blob/main/src/core/domain/entities/Product.ts): entities and rules · Business entities, constants, and domain error definitions · `src/core/domain/entities/Product.ts`

### Infrastructure

Database, repositories, security, AI adapters, and dependency containers

- [DB layer](https://github.com/jesgoy/argos/blob/main/src/infra/db/client.ts): persistence · Drizzle client, schema, and migrations for PostgreSQL · `src/infra/db/client.ts`
- [Repositories](https://github.com/jesgoy/argos/blob/main/src/infra/repositories/ProductRepositoryDrizzle.ts): adapters · Drizzle-backed persistence adapters for users, products, sales, and conversations · `src/infra/repositories/ProductRepositoryDrizzle.ts`
- [Security services](https://github.com/jesgoy/argos/blob/main/src/infra/security/HashServiceBcrypt.ts): adapters · Password hashing and JWT session issuance/verification · `src/infra/security/HashServiceBcrypt.ts`
- [AI adapter](https://github.com/jesgoy/argos/blob/main/src/infra/ai/VercelAIService.ts): external service · Vercel AI integration and model configuration · `src/infra/ai/VercelAIService.ts`
- [Containers](https://github.com/jesgoy/argos/blob/main/src/infra/container/auth.ts): composition root · Feature-level wiring for auth, products, sales, and AI dependencies · `src/infra/container/auth.ts`
- [Validation](https://github.com/jesgoy/argos/blob/main/src/infra/validation/auth.ts): input validation · Zod schemas for auth, products, sales, and conversations · `src/infra/validation/auth.ts`

## Connections

- App shell → Auth routes: routes · Public auth screens are mounted under the app shell
- App shell → Dashboard: routes · Protected workspace is mounted under the app shell
- Dashboard → Products UI: feature · Dashboard exposes product management screens
- Dashboard → Sales UI: feature · Dashboard exposes sales screens
- Dashboard → POS UI: feature · Dashboard exposes point-of-sale screens
- Dashboard → AI assistant: feature · Dashboard exposes assistant screens
- Auth routes → Auth use cases: invoke · Login and register pages delegate to auth use cases
- Products UI → Product use cases: invoke · Product forms and actions call product application logic
- Sales UI → Sales use cases: invoke · Sales screens call sales workflow use cases
- POS UI → Sales use cases: invoke · POS operations reuse sales and stock workflows
- AI assistant → AI command: invoke · Chat interface sends commands to AI orchestration
- AI assistant → Conversation use cases: invoke · Conversation history and API actions use conversation use cases
- Auth use cases → Ports: depends on · Auth logic depends on repository and session/hash interfaces
- Product use cases → Ports: depends on · Product logic depends on repository interfaces
- Sales use cases → Ports: depends on · Sales logic depends on repository interfaces
- Conversation use cases → Ports: depends on · Conversation logic depends on repository interfaces
- AI command → Ports: depends on · AI orchestration depends on AI and persistence ports
- Ports → Domain model: expresses · Ports are shaped by domain entities and business rules
- Repositories → DB layer: persists to · Repository implementations read and write through Drizzle
- Repositories → Domain model: maps · Adapters translate database records into domain objects
- Security services → Auth use cases: implements · Hash and session services satisfy auth use case dependencies
- AI adapter → AI command: implements · External AI service satisfies the AI port
- Containers → Auth use cases: wires · Composition roots assemble auth dependencies
- Containers → Product use cases: wires · Composition roots assemble product dependencies
- Containers → Sales use cases: wires · Composition roots assemble sales dependencies
- Containers → AI command: wires · Composition roots assemble AI dependencies
- Validation → Auth routes: guards · Request validation protects auth inputs
- Validation → Products UI: guards · Request validation protects product inputs
- Validation → Sales UI: guards · Request validation protects sales inputs
- Validation → AI assistant: guards · Request validation protects conversation and assistant inputs
