Architecture

From radix, shadcn, atoms, templates, blocks, micros — to full masterpiece.

Our architecture is engineered from the ground up for reusability, modularity, and a world-class developer experience. It's not just a system for building applications; it's a framework for composing "atomic" automation components into a powerful, collaborative, and AI-augmented ecosystem. We prioritize a scalable, feature-based structure to ensure that every contribution adds lasting, discoverable value to the entire codebase.

Core Architecture Principles

1. Component-Driven Modularity – Inspired by shadcn/ui philosophy, providing reusable, customizable components at their most minimal, essential state
2. Superior Developer Experience – Intuitive and predictable structure for productivity
3. Feature-Based & Composable – Micro-services and micro-frontends approach with independent components
4. Serverless-First – Deploy on Vercel with Neon Postgres for serverless DB
5. Type-Safety by Default – Prisma + Zod + TypeScript across the stack
6. Async-First – Small PRs, documented decisions, steady progress

Composition Hierarchy

• Foundation Layer: Radix UI → shadcn/ui → shadcn Ecosystem
• Building Blocks: UI → Atoms → Templates → Blocks → Micro → Apps

Mirror-Pattern

Every URL route produces two directories: one in app/ for routing and layouts, one in components/ for all feature logic. This 1:1 mapping means if you know the URL, you instantly know where to find both the page and its components.

For example, the route /abc creates:

• app/[lang]/abc/ — page.tsx, layout.tsx
• components/abc/ — content.tsx, actions.ts, form.tsx, validation.ts, types.ts, use-abc.ts, README.md, ISSUE.md, etc.

This predictable structure eliminates guesswork. New features follow the same pattern. Refactoring is straightforward. AI tools understand it instantly.

Tech Stack

• Framework: Next.js 16.0.3 with App Router and Turbopack, React 19.2.0, TypeScript
• Database: PostgreSQL with Prisma ORM 6.16.2, Neon for serverless
• Authentication: NextAuth v5 (beta) with Prisma adapter, OAuth and credentials
• Styling: Tailwind CSS v4 with OKLCH color format, custom design system
• UI Components: Radix UI primitives + custom shadcn/ui components
• Internationalization: Custom i18n with English/Arabic (RTL) support
• Documentation: MDX with custom components
• Runtime Strategy: Node.js runtime for Prisma/bcrypt pages, Edge runtime for others
• Type Safety: TypeScript Generics extensively used for reusability

Standardized File Patterns

Each feature directory follows these naming conventions:

Decision Framework

1. Mirror-Pattern First: Every new route in app/[lang]/ must have a mirrored directory in components/
2. Component Reusability: Start with shadcn/ui components, extend only when necessary
3. File Pattern Adherence: Use standardized file names (content.tsx, action.ts, etc.)
4. Type-Safety Chain: Zod schemas → TypeScript types → Prisma models
5. Serverless Compatibility: Default to Edge runtime unless Prisma/bcrypt required
6. Feature Isolation: Each feature should be independently deployable and testable
7. Progressive Enhancement: UI → Atoms → Templates → Blocks → Micro → Apps
8. Developer Experience: Predictable structure, clear naming, documented decisions

Naming Conventions

• Components: kebab-case for files (button.tsx, user-profile.tsx)
• Pages: kebab-case for route segments (user-profile, sign-in)
• Hooks: use-prefix convention (use-leads.ts, use-upwork.ts)
• Types: PascalCase for interfaces and types
• Constants: UPPER_SNAKE_CASE or camelCase for objects

Critical Files Reference

Anti-Pattern Detection

Watch out for these common mistakes:

• Components not following mirror-pattern structure
• Monolithic components that should be decomposed
• Missing type-safety chain (Zod validations, TypeScript types)
• Files not following standardized naming conventions
• Features with tight coupling preventing independent deployment
• Hardcoded values instead of using config.ts
• Direct database queries instead of using actions.ts patterns

A Typical Interaction

1. A user interacts with a component from form.tsx on the Next.js frontend, triggering a Server Action from actions.ts
2. The request payload is validated by a Zod schema from validation.ts
3. The serverless function uses the type-safe Prisma client to query Neon, using interfaces from types.ts
4. The result is streamed back and managed by a hook from use-abc.ts, efficiently updating the UI