Project Structure

Concordia follows a well-organized, modular file structure designed for scalability and maintainability.

Root Directory Structure

concordia/
├── src/                    # Source code
├── public/                 # Static assets
├── dist/                   # Build output
├── tests/                  # Test files
├── scripts/                # Utility scripts
├── .github/                # GitHub workflows and config
├── astro.config.mjs        # Astro configuration
├── tsconfig.json           # TypeScript configuration
├── drizzle.config.ts       # Drizzle ORM configuration
├── package.json            # Dependencies
└── .env                    # Environment variables

Source Directory (`src/`)

The src/ directory contains all application source code:

src/
├── actions/               # Server actions
├── components/            # UI components
├── database/              # Database layer
├── i18n/                  # Internationalization
├── layouts/               # Page layouts
├── lib/                   # Utility libraries
├── pages/                 # Routes and pages
├── styles/                # Global styles
└── env.d.ts               # Type definitions

Detailed Structure

Actions (`src/actions/`)

Server-side business logic and data mutations.

actions/
├── index.ts               # Action registry
├── blog.ts                # Blog post actions
├── comments.ts            # Comment actions
└── [feature].ts           # Feature-specific actions

Purpose:

Encapsulate business logic
Handle data validation
Perform database mutations
Return type-safe results

Example:

// actions/blog.ts
export const actions = {
  createPost: async (data: CreatePostInput) => {
    // Validate permissions
    // Validate input
    // Create database record
    // Return result
  },
};

Components (`src/components/`)

Reusable UI components organized by domain and purpose.

components/
├── Tools/                 # Layout utilities
│   ├── Flex.astro
│   ├── Grid.astro
│   └── SmartBreadcrumb.astro
├── admin/                 # Admin-specific components
│   ├── AdminToast.astro
│   ├── MarkdownEditor.astro
│   └── MediaPickerModal.astro
├── modules/               # Feature modules
│   ├── blog/
│   │   ├── cards/        # Card components
│   │   │   ├── AuthorCard.astro
│   │   │   └── PostCard.astro
│   │   ├── lists/        # List/grid components
│   │   │   ├── CategoryGrid.astro
│   │   │   ├── FeaturedGrid.astro
│   │   │   └── PostGrid.astro
│   │   ├── single/       # Single post components
│   │   │   ├── PostHeader.astro
│   │   │   ├── PostContent.astro
│   │   │   ├── PostComments.astro
│   │   │   └── TableOfContents.astro
│   │   └── ui/           # UI elements
│   │       ├── CategoryBadge.astro
│   │       ├── PostMeta.astro
│   │       ├── ShareButtons.astro
│   │       └── StarRating.astro
│   └── services/
│       ├── cards/
│       │   └── ServiceCard.astro
│       ├── lists/
│       │   ├── CategoryGrid.astro
│       │   └── ServiceGrid.astro
│       ├── single/
│       │   ├── ServiceHeader.astro
│       │   ├── ServiceBooking.astro
│       │   ├── AvailabilityCalendar.astro
│       │   └── ProviderCard.astro
│       └── ui/
│           ├── CategoryBadge.astro
│           ├── PriceBadge.astro
│           └── ServiceMeta.astro
├── templates/             # Page templates
│   ├── auth/             # Authentication pages
│   │   ├── AuthLayout.astro
│   │   ├── SignInCard.astro
│   │   ├── SignUpCard.astro
│   │   ├── ForgotPasswordForm.astro
│   │   ├── ResetPasswordForm.astro
│   │   ├── VerifyEmailCard.astro
│   │   └── profile/
│   │       ├── ProfileDetails.astro
│   │       ├── ProfileForm.astro
│   │       ├── ProfileHeader.astro
│   │       ├── ProfileInvitations.astro
│   │       └── ProfileOrganization.astro
│   ├── blog/
│   │   ├── BlogLayout.astro
│   │   ├── MainBlog.astro
│   │   ├── Sidebar.astro
│   │   └── navigation.ts
│   ├── docs/
│   │   ├── MainDoc.astro
│   │   ├── Sidebar.astro
│   │   ├── TableOfContents.astro
│   │   └── navigation.ts
│   ├── BannerPage.astro
│   ├── Footer/
│   │   └── Footer.astro
│   └── Header/
│       ├── Header.astro
│       ├── Brand.astro
│       ├── Navigation.astro
│       ├── LangChooser.astro
│       ├── ThemeSwitch.astro
│       └── User.astro
└── ui/                    # Base UI components
    ├── Accordion/
    │   ├── Accordion.astro
    │   └── AccordionItem.astro
    ├── Avatar/
    │   ├── Avatar.astro
    │   ├── AvatarCard.astro
    │   └── AvatarGroup.astro
    ├── Breadcrumb/
    │   ├── Breadcrumb.astro
    │   ├── BreadcrumbItem.astro
    │   ├── BreadcrumbLink.astro
    │   ├── BreadcrumbSeparator.astro
    │   └── PageBreadcrumb.astro
    ├── Card/
    │   ├── Card.astro
    │   ├── CardHeader.astro
    │   ├── CardContent.astro
    │   ├── CardFooter.astro
    │   └── CardImage.astro
    ├── Dialog/
    ├── Form/
    ├── Sheet/
    ├── Slider/
    ├── Table/
    ├── Tabs/
    ├── Alert.astro
    ├── Badge.astro
    ├── Button.astro
    └── ArticleCard.astro

Organization Pattern:

modules/ - Domain-specific components (blog, services, places)
templates/ - Page-level layouts and sections
ui/ - Reusable, generic UI components
Tools/ - Layout and utility components
admin/ - Admin-only components

Database (`src/database/`)

Database schemas, migrations, loaders, and seed data.

database/
├── schemas/               # Drizzle ORM schemas
│   ├── auth-schema.ts           # Better Auth tables
│   ├── audit-log.schema.ts      # Audit logging
│   ├── profile.schema.ts        # User profiles
│   ├── notification.schema.ts   # Notifications
│   ├── blog_posts.schema.ts
│   ├── blog_authors.schema.ts
│   ├── blog_categories.schema.ts
│   ├── blog_comments.schema.ts
│   ├── blog_media.schema.ts
│   ├── blog_organization.schema.ts
│   ├── blog_translations.schema.ts
│   ├── services_listings.schema.ts
│   ├── services_categories.schema.ts
│   ├── services_availability.schema.ts
│   ├── services_bookings.schema.ts
│   ├── services_reviews.schema.ts
│   ├── services_media.schema.ts
│   └── services_translations.schema.ts
├── loaders/               # Data loading functions
│   ├── factory.ts              # Loader factory
│   ├── blog.ts                 # Blog data loaders
│   └── services.ts             # Services data loaders
├── migrations/            # Database migrations
│   └── meta/                   # Migration metadata
├── admin/                 # Admin utilities
│   └── loaders.ts
├── data/                  # Seed data
│   ├── 01-user.data.ts
│   ├── 01-profile.data.ts
│   ├── 02-blog_authors.data.ts
│   ├── 03-blog_categories.data.ts
│   ├── 05-blog_media.data.ts
│   ├── 06-blog_organization.data.ts
│   ├── 07-blog_posts.data.ts
│   ├── 07-blog_post_authors.data.ts
│   ├── 10-blog_translations.data.ts
│   ├── 11-blog_comments.data.ts
│   ├── 11-notification.data.ts
│   ├── 20-services_media.data.ts
│   ├── 21-services_categories.data.ts
│   ├── 22-services_listings.data.ts
│   ├── 23-services_translations.data.ts
│   ├── 24-services_media_links.data.ts
│   ├── 25-services_availability.data.ts
│   ├── 26-services_reviews.data.ts
│   └── 27-services_bookings.data.ts
├── schemas.ts             # Schema exports
└── drizzle.ts             # Database connection

Key Files: drizzle.ts - Database connection and configuration:

export async function getDrizzle(): Promise<DrizzleDB>
export function getPgClient(): Client
export function getDbLabel(): string

schemas.ts - Centralized schema exports:

export * from './schemas/auth-schema';
export * from './schemas/blog_posts.schema';
// ... all schemas

loaders/ - Data loading utilities:

// loaders/blog.ts
export async function loadBlogPost(slug: string, lang: string)
export async function loadBlogPosts(filters: BlogFilters)

Library (`src/lib/`)

Shared utilities, helpers, and services.

lib/
├── admin/                 # Admin utilities
│   ├── api-helpers.ts
│   ├── config.ts
│   ├── history.ts
│   ├── loaders.ts
│   ├── markdown-editor.ts
│   ├── media-picker.ts
│   ├── organizations.ts
│   ├── permissions.ts
│   ├── policy-store.ts
│   ├── toast.ts
│   └── users.ts
├── auth/                  # Authentication
│   ├── auth.ts                  # Better Auth config
│   ├── auth-client.ts           # Client-side auth
│   ├── roles.ts                 # Role definitions
│   ├── permissions.ts           # Permission checks
│   ├── validate-user.ts         # User validation
│   ├── admin-access-control.ts  # Admin authorization
│   └── profile/
│       └── utils.ts
├── i18n/                  # Internationalization
│   ├── locale-url.ts            # URL helpers
│   └── route-helpers.ts         # Route utilities
├── notifications/         # Notification system
│   └── notifications.ts
├── smtp/                  # Email
│   ├── smtp.ts
│   └── smtp.check.ts
├── types.ts               # Global types
└── theme.ts               # Theme utilities

Pages (`src/pages/`)

File-based routing structure.

pages/
├── [lang]/                # Language-based routes
│   ├── index.astro               # Homepage
│   ├── admin/                    # Admin panel
│   │   ├── index.astro
│   │   ├── blog/
│   │   │   ├── index.astro
│   │   │   ├── new.astro
│   │   │   ├── categories.astro
│   │   │   └── [id]/
│   │   │       ├── index.astro
│   │   │       └── edit.astro
│   │   ├── services/
│   │   │   ├── index.astro
│   │   │   ├── [id]/
│   │   │   ├── bookings/
│   │   │   └── categories/
│   │   └── users/
│   ├── auth/                     # Authentication
│   │   ├── sign-in.astro
│   │   ├── sign-up.astro
│   │   ├── forgot-password.astro
│   │   ├── reset-password.astro
│   │   └── verify-email.astro
│   ├── blog/                     # Blog
│   │   ├── index.astro
│   │   ├── [slug].astro          # Single post
│   │   ├── [category]/
│   │   │   └── index.astro
│   │   └── author/
│   │       └── [authorId].astro
│   ├── services/                 # Services
│   │   ├── index.astro
│   │   ├── [slug].astro          # Single service
│   │   └── [category]/
│   │       └── index.astro
│   ├── docs/                     # Documentation
│   │   ├── index.astro
│   │   ├── components/
│   │   ├── design/
│   │   ├── layouts/
│   │   └── templates/
│   ├── organizations/
│   │   ├── index.astro
│   │   └── [slug]/
│   └── profile.astro
├── api/                   # API routes
│   ├── auth/                     # Better Auth endpoints
│   │   └── [...all].ts
│   ├── auth-client/              # Auth client
│   │   └── [...all].ts
│   ├── admin/                    # Admin API
│   │   ├── blog/
│   │   ├── services/
│   │   └── organizations/
│   ├── profile/
│   └── services/
└── index.astro            # Root redirect

Routing Patterns:

[lang]/ - Dynamic language parameter (fr, en, ar, es)
[slug].astro - Dynamic route for content
[...all].ts - Catch-all route
api/ - Server-side API endpoints

Example Routes:

/fr/blog/ma-premiere-ville          → /[lang]/blog/[slug].astro
/en/services/plumbing               → /[lang]/services/[slug].astro
/fr/admin/blog/123/edit             → /[lang]/admin/blog/[id]/edit.astro
/api/auth/sign-in                   → /api/auth/[...all].ts

Internationalization (`src/i18n/`)

Translation files organized by locale.

i18n/
├── fr.json                # French translations
├── en.json                # English translations
├── ar.json                # Arabic translations
└── es.json                # Spanish translations

Translation Structure:

{
  "common": {
    "home": "Accueil",
    "about": "À propos",
    "contact": "Contact"
  },
  "auth": {
    "signIn": "Se connecter",
    "signUp": "S'inscrire",
    "signOut": "Se déconnecter"
  },
  "blog": {
    "title": "Blog",
    "readMore": "Lire la suite",
    "author": "Auteur"
  }
}

Styles (`src/styles/`)

Global CSS and design tokens.

styles/
├── components/            # Component styles
├── tokens/                # Design tokens
└── global.css             # Global styles

Testing Structure

tests/
├── unit/                  # Unit tests
│   ├── lib/
│   └── components/
├── integration/           # Integration tests
│   ├── auth-flow.test.ts
│   └── api/
├── e2e/                   # End-to-end tests
│   ├── critical-flows.test.ts
│   └── ui/
└── security/              # Security tests
    └── security.test.ts

Scripts Directory

scripts/
├── db/                    # Database utilities
│   ├── db.check.ts
│   ├── db.compare.ts
│   ├── db.sync.ts
│   ├── db.migrate.ts
│   ├── db.generate.ts
│   └── db.seed.ts
├── contextai/             # Context.ai integration
│   └── injectScope.ts
├── readme-generate.ts     # README generation
└── run-sonda.mjs          # Bundle analysis

Common Commands:

pnpm db:generate           # Generate migrations
pnpm db:migrate            # Run migrations
pnpm db:seed               # Seed database
pnpm db:check              # Check database status

Configuration Files

`astro.config.mjs`

Astro framework configuration:

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [mdx()],
  i18n: {
    defaultLocale: 'fr',
    locales: ['fr', 'en', 'ar', 'es'],
  },
});

`drizzle.config.ts`

Drizzle ORM configuration:

export default {
  schema: './src/database/schemas.ts',
  out: './src/database/migrations',
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
};

`tsconfig.json`

TypeScript configuration:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Naming Conventions

Files

Components: PascalCase.astro (e.g., PostCard.astro)
Utilities: kebab-case.ts (e.g., locale-url.ts)
Schemas: entity_name.schema.ts (e.g., blog_posts.schema.ts)
Tests: *.test.ts or *.spec.ts

Code

Variables/Functions: camelCase
Types/Interfaces: PascalCase
Constants: SCREAMING_SNAKE_CASE
Database Tables: snake_case

Best Practices

Colocation: Keep related files close (components, styles, tests)
Feature Modules: Group by domain/feature, not by file type
Index Files: Use index.ts for clean imports
Type Imports: Import types from schemas, not from ORM
Barrel Exports: Export from index.ts for public APIs

Next Steps

Architecture Overview - System design and patterns
Tech Stack - Technology details
Development Guide - Setup and workflow

​Project Structure

​Root Directory Structure

​Source Directory (src/)

​Detailed Structure

​Actions (src/actions/)

​Components (src/components/)

​Database (src/database/)

​Library (src/lib/)

​Pages (src/pages/)

​Internationalization (src/i18n/)

​Styles (src/styles/)

​Testing Structure

​Scripts Directory

​Configuration Files

​astro.config.mjs

​drizzle.config.ts

​tsconfig.json

​Naming Conventions

​Files

​Code

​Best Practices

​Next Steps