EMTB Source Tree Organization

Overview

The EMTB Tax Claim Management System follows a monorepo architecture with independent applications for API and frontend, organized for optimal development workflow and role-based access control implementation.

Root Directory Structure

emtb/
├── .bmad-core/                 # AI agent configurations and templates
├── .claude/                    # Claude Code configurations  
├── .cursor/                    # Cursor IDE configurations
├── .github/                    # GitHub Actions workflows and templates
│   ├── workflows/              # CI/CD pipeline definitions
│   └── ISSUE_TEMPLATE/         # Issue and PR templates
├── .git/                       # Git repository data
├── apps/                       # Application packages (main development)
│   ├── api/                    # NestJS backend application
│   └── frontend/               # Next.js frontend application
├── docs/                       # Project documentation
│   ├── architecture/           # Technical architecture documents
│   ├── prd.md                  # Product Requirements Document
│   └── architecture.md         # Main architecture specification
├── web-bundles/                # Generated bundle assets
├── README.md                   # Project overview and setup
├── RENDER_DEPLOYMENT.md        # Render.com deployment guide
├── RENDER_TROUBLESHOOTING.md   # Infrastructure troubleshooting
└── render.yaml                 # Render.com service definitions

Backend Application Structure (apps/api/)

Core Organization

apps/api/
├── src/
│   ├── main.ts                 # Application entry point
│   ├── app.module.ts           # Root application module
│   ├── app.controller.ts       # Health check and root endpoints
│   ├── app.service.ts          # Root application services
│   │
│   ├── prisma/                 # Database connection and configuration
│   │   ├── prisma.module.ts    # Prisma module definition
│   │   └── prisma.service.ts   # Database service with connection pooling
│   │
│   ├── client/                 # Client management domain
│   │   ├── client.module.ts    # Client module with dependencies
│   │   ├── client.controller.ts # REST endpoints for client operations
│   │   ├── client.service.ts   # Business logic for client management
│   │   ├── client.service.spec.ts # Unit tests for client service
│   │   ├── client.controller.spec.ts # Controller unit tests
│   │   └── dto/                # Data Transfer Objects
│   │       ├── create-client.dto.ts
│   │       └── update-client.dto.ts
│   │
│   ├── site/                   # Site management domain
│   │   ├── site.module.ts      # Site module definition
│   │   └── [similar structure to client/]
│   │
│   ├── reclamation/            # Tax claim management domain
│   │   ├── reclamation.module.ts
│   │   └── [similar structure to client/]
│   │
│   ├── facture/                # Invoice management domain
│   │   └── facture.module.ts
│   │
│   ├── user/                   # User management domain  
│   │   └── user.module.ts
│   │
│   ├── apporteur-affaire/      # Partner/referrer management
│   │   └── apporteur-affaire.module.ts
│   │
│   ├── facture-partenaire/     # Partner invoice management
│   │   └── facture-partenaire.module.ts
│   │
│   ├── cadastre/               # Property/cadastral data management
│   │   ├── cadastre.module.ts
│   │   ├── cadastre.controller.ts
│   │   ├── cadastre.service.ts
│   │   └── dto/
│   │       ├── create-cadastre.dto.ts
│   │       └── update-cadastre.dto.ts
│   │
│   ├── import/                 # Data import functionality
│   │   ├── import.module.ts    # Import service module
│   │   ├── import.service.ts   # Data import logic
│   │   └── import.service.spec.ts # Import testing
│   │
│   ├── cli/                    # Command-line interface
│   │   ├── cli.module.ts       # CLI module definition  
│   │   └── import.command.ts   # Import command implementation
│   │
│   ├── scripts/                # Utility and maintenance scripts
│   │   ├── fix-json-data.ts    # Data cleanup scripts
│   │   ├── fix-json-data.spec.ts
│   │   ├── validate-import-data.ts # Data validation scripts
│   │   └── validate-import-data.spec.ts
│   │
│   └── cli.ts                  # CLI entry point
│
├── test/                       # End-to-end and integration tests
│   └── jest-e2e.json          # E2E testing configuration
│
├── prisma/                     # Database schema and migrations
│   ├── schema.prisma          # Database schema definition
│   └── migrations/            # Database migration files
│
├── package.json               # Backend dependencies and scripts
└── tsconfig.json              # TypeScript configuration

Domain Module Pattern

Each domain (client, site, reclamation, etc.) follows a consistent structure:

domain/
├── domain.module.ts           # NestJS module with providers and exports
├── domain.controller.ts       # HTTP endpoints with Swagger documentation
├── domain.service.ts          # Business logic and Prisma integration
├── domain.controller.spec.ts  # Controller unit tests
├── domain.service.spec.ts     # Service unit tests
└── dto/                       # Data Transfer Objects
    ├── create-domain.dto.ts   # Creation DTOs with validation
    └── update-domain.dto.ts   # Update DTOs (usually extends CreateDto)

Frontend Application Structure (apps/frontend/)

Core Organization

apps/frontend/
├── app/                        # Next.js 14 App Router structure
│   ├── layout.tsx              # Root layout with providers
│   ├── page.tsx                # Home page component
│   ├── loading.tsx             # Loading UI component
│   ├── error.tsx               # Error boundary component
│   ├── not-found.tsx           # 404 page component
│   │
│   ├── api/                    # API routes (Next.js API routes)
│   │   └── auth/               # Auth0 API routes
│   │
│   ├── protected/              # Authenticated routes
│   │   ├── layout.tsx          # Protected area layout
│   │   ├── dashboard/          # Dashboard pages
│   │   ├── clients/            # Client management pages
│   │   ├── reclamations/       # Tax claim pages
│   │   └── reports/            # Reporting pages
│   │
│   └── auth/                   # Authentication pages
│       ├── login/
│       ├── logout/
│       └── callback/
│
├── components/                 # Reusable UI components
│   ├── shared/                 # Generic shared components
│   │   ├── List.tsx            # Generic data list component
│   │   ├── ConfirmationDialog.tsx # Confirmation modals
│   │   └── LoadingSpinner.tsx  # Loading indicators
│   │
│   ├── layout/                 # Layout-specific components
│   │   ├── Header.tsx          # Application header
│   │   ├── Sidebar.tsx         # Navigation sidebar
│   │   └── Footer.tsx          # Application footer
│   │
│   └── forms/                  # Form components
│       ├── FormField.tsx       # Generic form field wrapper
│       └── ValidationMessage.tsx # Form validation display
│
├── domains/                    # Domain-specific components and logic
│   ├── clients/                # Client management domain
│   │   ├── components/         # Client-specific components
│   │   │   ├── ClientsList.tsx # Client listing component
│   │   │   ├── ClientShortDetails.tsx # Client summary
│   │   │   └── forms/          # Client form components
│   │   │       ├── ClientForm.tsx
│   │   │       ├── ContactForm.tsx
│   │   │       ├── PartnerForm.tsx
│   │   │       ├── PartnerSelectList.tsx
│   │   │       ├── MandatForm.tsx
│   │   │       ├── ConventionForm.tsx
│   │   │       └── GeneralInformationForm.tsx
│   │   │
│   │   └── hooks/              # Client-specific hooks
│   │       └── queries/        # React Query hooks
│   │           └── clients.ts  # Client data fetching hooks
│   │
│   ├── reclamations/           # Tax claim management domain
│   ├── sites/                  # Site management domain
│   └── reports/                # Reporting domain
│
├── contexts/                   # React Context providers
│   ├── AuthProvider.tsx        # Auth0 context wrapper
│   ├── ThemeProvider.tsx       # MUI theme context
│   └── SnackbarProvider.tsx    # Global notification context
│
├── hooks/                      # Shared custom hooks
│   ├── useAuth.ts              # Authentication state hook
│   ├── useLocalStorage.ts      # Local storage utilities
│   └── useDebounce.ts          # Debouncing utilities
│
├── shared/                     # Shared utilities and services
│   ├── services/               # API service layer
│   │   ├── client.ts           # Client API service
│   │   ├── reclamation.ts      # Tax claim API service
│   │   └── api.ts              # Base API client
│   │
│   ├── query-keys.ts           # React Query key definitions
│   ├── constants.ts            # Application constants
│   └── utils.ts                # Utility functions
│
├── types/                      # TypeScript type definitions
│   ├── next-auth.d.ts         # Next-auth type extensions
│   ├── strapi.dts.ts          # Generated API types
│   ├── shared.ts              # Shared type definitions
│   ├── theme.ts               # MUI theme types
│   ├── sidebar.ts             # Navigation types
│   ├── autocomplete-option.ts # Form component types
│   ├── images.d.ts            # Image asset types
│   └── emotion.d.ts           # Emotion CSS types
│
├── theme/                      # MUI theme configuration
│   ├── index.ts               # Theme provider and configuration
│   └── components/            # Component-specific theme overrides
│
├── utils/                      # Utility functions and helpers
│   ├── constants.ts           # Global constants
│   ├── formatters.ts          # Data formatting utilities
│   └── validators.ts          # Form validation utilities
│
├── vendor/                     # Third-party assets and configurations
│   └── mui/                   # Material-UI specific customizations
│
├── middleware.ts              # Next.js middleware (authentication)
├── constants.js               # Legacy constants (to be migrated)
├── next.config.js            # Next.js configuration
├── tailwind.config.js        # Tailwind CSS configuration
├── postcss.config.js         # PostCSS configuration  
├── tsconfig.json             # TypeScript configuration
├── jest.config.ts            # Jest testing configuration
├── jest.setup.ts             # Jest setup and global mocks
└── package.json              # Frontend dependencies and scripts

Key Architectural Patterns

Backend Patterns

1. Module-based Organization: Each business domain has its own NestJS module
2. Controller-Service Pattern: Clear separation between HTTP handling and business logic
3. DTO Pattern: Validation and type safety with class-validator decorators
4. Repository Pattern: Prisma service acts as repository layer
5. CLI Integration: Command pattern for data management operations

Frontend Patterns

1. Domain-driven Organization: Components organized by business domain
2. Atomic Design: Shared components, domain-specific components, page layouts
3. Custom Hook Pattern: React Query integration with domain-specific hooks
4. Service Layer Pattern: Centralized API communication layer
5. Provider Pattern: Context-based state management

RBAC Implementation Structure (Planned)

Backend RBAC Structure

src/
├── auth/                       # RBAC authentication and authorization
│   ├── guards/                 # Role-based route guards
│   ├── decorators/             # Role requirement decorators
│   ├── services/               # Authentication services
│   └── middleware/             # Tenant context middleware
│
├── tenant/                     # Multi-tenant data isolation
│   ├── services/               # Tenant context management
│   └── middleware/             # Prisma middleware for filtering
│
└── audit/                      # Security audit logging
    ├── services/               # Audit log services
    └── models/                 # Audit data models

Frontend RBAC Structure

src/
├── contexts/
│   └── RoleContext.tsx         # Role-based state management
│
├── components/
│   └── rbac/                   # Role-aware UI components
│       ├── ProtectedRoute.tsx  # Route protection
│       └── RoleBasedRender.tsx # Conditional rendering
│
└── hooks/
    ├── useRole.ts              # Role state management
    └── usePermissions.ts       # Permission checking

File Naming Conventions

Backend (NestJS/TypeScript)

• Modules: domain.module.ts (kebab-case for domain, PascalCase for class)
• Controllers: domain.controller.ts (REST endpoint handlers)
• Services: domain.service.ts (business logic)
• DTOs: create-domain.dto.ts, update-domain.dto.ts (kebab-case files)
• Tests: *.spec.ts (same name as tested file)

Frontend (Next.js/React/TypeScript)

• Components: ComponentName.tsx (PascalCase)
• Pages: page.tsx, layout.tsx (Next.js App Router convention)
• Hooks: useHookName.ts (camelCase with 'use' prefix)
• Services: serviceName.ts (camelCase)
• Types: typeName.ts or domain.types.ts (camelCase)

Import Path Conventions

Backend Imports

// Relative imports within same module
import { CreateClientDto } from './dto/create-client.dto';

// Absolute imports for cross-module
import { PrismaService } from '../prisma/prisma.service';

Frontend Imports

// Absolute imports using path mapping (tsconfig.json)
import { ClientService } from '$shared/services/client';
import { useAuth } from '$hooks/useAuth';
import FormField from '$components/forms/FormField';

// Domain-specific imports
import { ClientForm } from '$domains/clients/components/forms/ClientForm';

Build and Development Organization

Package Scripts

• Development: npm run dev (both apps), npm run dev:api, npm run dev:frontend
• Building: npm run build (both apps), npm run build:api, npm run build:frontend
• Testing: npm run test, npm run test:unit, npm run test:e2e
• Linting: npm run lint (both apps with --fix)
• Type Checking: npm run type:check (TypeScript validation)

Deployment Structure

• Production Build: Separate Docker containers for API and frontend
• Environment Variables: App-specific .env files
• Database Migrations: Handled via Prisma migrate in deployment pipeline

This source tree organization supports the RBAC enhancement by providing clear separation of concerns, consistent patterns, and scalable architecture for multi-tenant security implementation.