How jesgoy/argos works
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: ProductRepository.ts Ports · layout.tsx Dashboard · container/auth.ts Containers · validation/auth.ts Validation
Components 20
Presentation
Next.js App Router routes, pages, components, and server actions
- App shell · Root layout, landing page, and shared app chrome
src/app/layout.tsx - Auth routes · Login and registration screens with server actions
src/app/(auth)/login/page.tsx - Dashboard · Authenticated workspace for products, sales, POS, AI, and logout
src/app/(dashboard)/layout.tsx - Products UI · Product list, create/edit forms, and product actions
src/app/(dashboard)/products/page.tsx - Sales UI · Sales list and sales-related actions
src/app/(dashboard)/sales/page.tsx - POS UI · Point-of-sale interface and checkout actions
src/app/(dashboard)/pos/page.tsx - AI assistant · 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 · Login, registration, session lookup, and role authorization
src/core/application/usecases/auth/LoginUser.ts - Product use cases · Create, read, update, and delete products
src/core/application/usecases/products/CreateProduct.ts - Sales use cases · Process sales, cancel sales, adjust stock, and reporting
src/core/application/usecases/sales/ProcessSale.ts - Conversation use cases · Create, fetch, list history, and delete conversations and messages
src/core/application/usecases/conversations/CreateConversation.ts - AI command · Interprets chat intent and coordinates AI responses
src/core/application/usecases/ai/ProcessAICommand.ts - Ports · Repository and service interfaces used by application code
src/core/application/ports/ProductRepository.ts
Domain
Core business entities, constants, and rule errors
- Domain model · Business entities, constants, and domain error definitions
src/core/domain/entities/Product.ts
Infrastructure
Database, repositories, security, AI adapters, and dependency containers
- DB layer · Drizzle client, schema, and migrations for PostgreSQL
src/infra/db/client.ts - Repositories · Drizzle-backed persistence adapters for users, products, sales, and conversations
src/infra/repositories/ProductRepositoryDrizzle.ts - Security services · Password hashing and JWT session issuance/verification
src/infra/security/HashServiceBcrypt.ts - AI adapter · Vercel AI integration and model configuration
src/infra/ai/VercelAIService.ts - Containers · Feature-level wiring for auth, products, sales, and AI dependencies
src/infra/container/auth.ts - Validation · Zod schemas for auth, products, sales, and conversations
src/infra/validation/auth.ts
Connections 30
- 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