Project Structure

Last Updated: 2025-11-22

Overview

AccessALI follows a well-organized, layered architecture with clear separation of concerns. This guide provides a comprehensive overview of the project structure and file organization.

File Organization

The project uses a feature-based organization within a layered architecture, making it easy to locate and modify code.

Directory Tree

accessali/
├── src/                          # Application source code
│   ├── app/                       # Next.js 15 App Router
│   │   ├── (auth)/                # Auth pages (login, register)
│   │   ├── (dashboard)/           # Protected dashboard pages
│   │   ├── actions/               # Server Actions
│   │   ├── api/                   # API Routes
│   │   ├── fonts/                 # Font files
│   │   ├── globals.css            # Global styles
│   │   ├── layout.tsx             # Root layout
│   │   └── page.tsx               # Landing/home page
│   │
│   ├── components/                # React components
│   │   ├── ui/                    # shadcn/ui primitives
│   │   ├── auth/                  # Authentication components
│   │   ├── dashboard/             # Dashboard components
│   │   ├── layout/                # Layout components
│   │   └── shared/                # Shared/common components
│   │
│   ├── lib/                       # Business logic & utilities
│   │   ├── adapters/              # Mock/Real API adapters
│   │   ├── integrations/          # Real API clients
│   │   ├── mocks/                 # Mock implementations
│   │   ├── repositories/          # Data access layer
│   │   ├── services/              # Business services
│   │   ├── use-cases/             # Application use cases
│   │   ├── validators/            # Zod validation schemas
│   │   ├── auth.ts                # NextAuth.js configuration
│   │   ├── prisma.ts              # Prisma client
│   │   ├── types.ts               # TypeScript types
│   │   └── utils.ts               # Utility functions
│   │
│   ├── prisma/                    # Database
│   │   ├── migrations/            # SQL migrations
│   │   ├── schema.prisma          # Database schema
│   │   └── seed.ts                # Seed data
│   │
│   ├── public/                    # Static assets
│   │   ├── images/                # Images
│   │   └── icons/                 # Icons
│   │
│   ├── styles/                    # CSS files
│   │   └── globals.css            # Global styles
│   │
│   ├── types/                     # TypeScript type definitions
│   │   └── next-auth.d.ts         # NextAuth type extensions
│   │
│   ├── middleware.ts              # Next.js middleware
│   ├── next.config.mjs            # Next.js configuration
│   ├── tailwind.config.ts         # Tailwind CSS configuration
│   ├── tsconfig.json              # TypeScript configuration
│   └── package.json               # Dependencies
│
├── docs/                          # MkDocs documentation
│   ├── architecture/              # Architecture docs
│   ├── api/                       # API documentation
│   ├── components/                # Component docs
│   ├── deployment/                # Deployment docs
│   ├── getting-started/           # Getting started guides
│   └── guide/                     # Development guides
│
├── docker/                        # Docker configuration
│   ├── scripts/                   # Helper scripts
│   └── postgres/                  # PostgreSQL config
│
├── k8s/                           # Kubernetes manifests
│   ├── app/                       # Application deployment
│   ├── database/                  # Database deployment
│   └── ingress/                   # Ingress configuration
│
├── .github/                       # GitHub configuration
│   ├── workflows/                 # GitHub Actions
│   └── PULL_REQUEST_TEMPLATE.md   # PR template
│
├── docker-compose.yml             # Development services
├── docker-compose.prod.yml        # Production services
├── Dockerfile                     # Production image
├── Dockerfile.dev                 # Development image
├── .env.docker                    # Docker environment
├── .env.example                   # Environment template
├── .gitignore                     # Git ignore rules
├── mkdocs.yml                     # Documentation config
├── CLAUDE.md                      # AI assistant guide
├── README.md                      # Project overview
└── package.json                   # Root dependencies

Source Code Organization

App Router (src/app/)

Next.js 15 App Router follows file-system based routing:

app/
├── (auth)/                   # Route group (no URL segment)
│   ├── login/
│   │   └── page.tsx           # /login
│   ├── register/
│   │   └── page.tsx           # /register
│   └── layout.tsx             # Layout for auth pages
│
├── (dashboard)/              # Route group (authenticated)
│   ├── dashboard/
│   │   └── page.tsx           # /dashboard
│   ├── properties/
│   │   ├── page.tsx           # /properties
│   │   └── [id]/
│   │       └── page.tsx       # /properties/:id
│   ├── payments/
│   │   └── page.tsx           # /payments
│   ├── documents/
│   │   └── page.tsx           # /documents
│   └── layout.tsx             # Layout for dashboard
│
├── actions/                  # Server Actions
│   ├── auth.ts                # Authentication actions
│   ├── dashboard.ts           # Dashboard actions
│   ├── properties.ts          # Property actions
│   └── payments.ts            # Payment actions
│
├── api/                      # API Routes
│   ├── auth/                  # NextAuth.js routes
│   ├── upload/                # File upload endpoint
│   └── webhooks/              # Webhook endpoints
│
├── layout.tsx                # Root layout
└── page.tsx                  # Landing page (/)

Components (src/components/)

components/
├── ui/                       # shadcn/ui primitives
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   └── ...
│
├── auth/                     # Authentication
│   ├── login-form.tsx
│   ├── register-form.tsx
│   └── oauth-buttons.tsx
│
├── dashboard/                # Dashboard features
│   ├── property-card.tsx
│   ├── milestone-tracker.tsx
│   ├── payment-summary.tsx
│   └── recent-documents.tsx
│
├── layout/                   # Layout components
│   ├── header.tsx
│   ├── footer.tsx
│   ├── sidebar.tsx
│   └── nav.tsx
│
└── shared/                   # Shared/reusable
    ├── loading-spinner.tsx
    ├── error-boundary.tsx
    ├── data-table.tsx
    └── empty-state.tsx

Business Logic (src/lib/)

lib/
├── adapters/                 # Mock/Real API switching
│   ├── base-adapter.ts        # Adapter factory
│   ├── sap-adapter.ts         # SAP integration adapter
│   ├── salesforce-adapter.ts  # Salesforce adapter
│   └── springcm-adapter.ts    # SpringCM adapter
│
├── integrations/             # Real API clients
│   ├── sap-client.ts          # SAP API client
│   ├── salesforce-client.ts   # Salesforce client
│   └── springcm-client.ts     # SpringCM client
│
├── mocks/                    # Mock implementations
│   ├── sap-mock.ts            # SAP mock data
│   ├── salesforce-mock.ts     # Salesforce mock
│   └── springcm-mock.ts       # SpringCM mock
│
├── repositories/             # Data access layer
│   ├── user-repository.ts     # User CRUD
│   ├── property-repository.ts # Property CRUD
│   ├── payment-repository.ts  # Payment CRUD
│   └── errors.ts              # Repository errors
│
├── services/                 # Business services
│   ├── email-service.ts       # Email sending
│   ├── file-upload-service.ts # File uploads
│   └── notification-service.ts # Notifications
│
├── use-cases/                # Application use cases
│   ├── dashboard.ts           # Dashboard logic
│   ├── properties.ts          # Property logic
│   └── payments.ts            # Payment logic
│
├── validators/               # Zod schemas
│   ├── auth.ts                # Auth validation
│   ├── property.ts            # Property validation
│   └── payment.ts             # Payment validation
│
├── auth.ts                   # NextAuth config
├── prisma.ts                 # Prisma client
├── types.ts                  # TypeScript types
└── utils.ts                  # Utilities

Naming Conventions

Files

page.tsx                      # Next.js page
layout.tsx                    # Next.js layout
loading.tsx                   # Next.js loading UI
error.tsx                     # Next.js error UI
not-found.tsx                 # 404 page

user-repository.ts            # Repository (kebab-case)
auth-service.ts               # Service (kebab-case)
dashboard-use-case.ts         # Use case (kebab-case)

button.tsx                    # Component (kebab-case)
data-table.tsx                # Component (kebab-case)

types.ts                      # TypeScript types
index.ts                      # Barrel export

Components

// Component names: PascalCase
export function PropertyCard() { }
export function DashboardHeader() { }

// File names: kebab-case
property-card.tsx
dashboard-header.tsx

Functions

// Functions: camelCase
export function getUserById() { }
export async function createPayment() { }

// Constants: UPPER_SNAKE_CASE
export const MAX_FILE_SIZE = 5000000
export const API_BASE_URL = 'https://api.example.com'

// Types: PascalCase
export type UserRole = 'BUYER' | 'ADMIN'
export interface PropertyDetails { }

Import Paths

Absolute Imports

Use @/ alias for all imports:

// ✅ Good
import { Button } from '@/components/ui/button'
import { prisma } from '@/lib/prisma'
import { getUserById } from '@/lib/repositories/user-repository'

// ❌ Avoid
import { Button } from '../../components/ui/button'
import { prisma } from '../lib/prisma'

Import Order

// 1. External dependencies
import { z } from 'zod'
import { NextRequest } from 'next/server'

// 2. Internal dependencies (@/ imports)
import { prisma } from '@/lib/prisma'
import { Button } from '@/components/ui/button'

// 3. Relative imports (only for same directory)
import { localHelper } from './helper'
import type { LocalType } from './types'

Configuration Files

TypeScript (tsconfig.json)

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "jsx": "preserve",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Next.js (next.config.mjs)

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
    },
  },
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.vercel-storage.com',
      },
    ],
  },
}

export default nextConfig

Tailwind CSS (tailwind.config.ts)

import type { Config } from 'tailwindcss'

const config: Config = {
  darkMode: ['class'],
  content: [
    './pages/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
    './src/**/*.{ts,tsx}',
  ],
  theme: {
    extend: {
      // Custom theme extensions
    },
  },
  plugins: [require('tailwindcss-animate')],
}

export default config

Environment Variables

Development (.env.docker)

DATABASE_URL="postgresql://postgres:postgres@postgres:5432/accessali"
NEXTAUTH_SECRET="dev-secret"
USE_MOCK_SAP="true"

Local (.env.local)

DATABASE_URL="postgresql://user:pass@localhost:5432/accessali"
NEXTAUTH_SECRET="local-secret"
USE_MOCK_SAP="true"

Production (Vercel)

DATABASE_URL="postgresql://user:pass@neon.tech/db"
NEXTAUTH_SECRET="strong-random-secret"
USE_MOCK_SAP="false"
SAP_API_URL="https://sap.company.com/api"

Related Documentation

• Development Workflow - Development process
• Docker Guide - Docker setup
• Coding Conventions - Code style
• Layered Architecture - Architecture details

Next Steps

• Review coding conventions
• Understand layered architecture
• Explore development workflow