Stack Overview
CardNexus is a multi-platform trading card inventory and sales management system built as a Turborepo monorepo.
Backend
| Technology | Purpose |
|---|---|
| Node.js + TypeScript | Runtime & Language |
| Express | HTTP Server |
| oRPC | Contract-first API framework |
| MongoDB + Mongoose | Database & ODM |
| TSyringe | Dependency Injection |
| Vitest | Testing |
| Biome | Linting & Formatting |
Key Patterns
- Layered Architecture: Handlers → Features → Domains → Views → Foundation
- Contract-First API: Define schemas in
@repo/api-dtos, implement in@repo/api - Result Pattern: Services return
Result<T, E>using neverthrow - Event-Driven: Domain events for cross-cutting concerns
See the Backend Introduction for detailed architecture documentation.
Frontend
| Technology | Purpose |
|---|---|
| Next.js 15 | React Framework (App Router) |
| Tailwind CSS | Styling |
| Jotai | State Management |
| TanStack Query | Server State |
| Zod | Validation |
| Clerk | Authentication |
Key Patterns
- Atomic Design: Component architecture principles
- Type-Safe API: oRPC client with full type inference
- Form Atoms: jotai-form for form state
Mobile
| Technology | Purpose |
|---|---|
| React Native + Expo | Framework |
| NativeWind | Styling (Tailwind for RN) |
| Jotai | State Management |
| Drizzle + SQLite | Local Database |
Key Patterns
- Atomic File Organization:
queries.ts,mutations.ts,ui.ts,effects.ts - Offline-First: SQLite for local persistence
- Template-Based Creation: Mutation atoms for inventory management
Infrastructure
| Service | Platform |
|---|---|
| Frontend | Vercel |
| Backend | AWS ECS |
| Database | MongoDB Atlas |
| Search | OpenSearch |
| Queues | AWS SQS |
| Storage | AWS S3 |
| Background Jobs | Trigger.dev |
| Mobile Builds | EAS |
Local Development Stack
Docker Compose provides these services locally:
| Service | Port | Purpose |
|---|---|---|
| MongoDB | 27017 | Database |
| LocalStack | 4566 | AWS services (SQS, SNS, S3) |
| OpenSearch | 9200 | Search engine |
Monorepo Structure
/cardnexus
├── apps/
│ ├── frontend/ # Next.js web app (port 4200)
│ ├── backend/ # Express API server (port 3000)
│ ├── mobile/ # React Native app
│ ├── admin/ # Vite admin app
│ └── cli/ # oclif CLI tool
├── packages/
│ ├── api/ # oRPC handlers
│ ├── api-dtos/ # oRPC contracts (schemas)
│ ├── db/ # Mongoose models
│ ├── ui/ # Shared UI components
│ └── ...We use WallabyJS locally to speed up testing - highly recommended.
Last updated on