Project Structure

The portfolio website follows Astro’s recommended project structure with custom organization for internationalization, components, and assets.

Overview

The project is organized to separate concerns clearly:

Configuration files at the root
Source code in src/
Static assets in public/
Build output in dist/ (generated)

Root Directory

portfolio/
├── astro.config.mjs          # Astro configuration
├── tailwind.config.mjs       # Tailwind CSS configuration
├── package.json              # Dependencies and scripts
├── package-lock.json         # Lock file for dependencies
├── .gitignore               # Git ignore rules
├── README.md                # Project documentation
├── public/                  # Static assets
├── src/                     # Source code
└── dist/                    # Production build (generated)

Configuration Files

astro.config.mjs

Purpose: Main Astro configuration fileContains:

i18n setup (locales, routing)
Integrations (Tailwind)
Build optimizations (Vite/Terser)

Reference: See Astro ConfigurationLocation: astro.config.mjs:1

tailwind.config.mjs

Purpose: Tailwind CSS customizationContains:

Custom color schemes (primary, accent)
Custom animations (float, gradient, border-spin)
Font family configuration
Dark mode settings

Reference: See Tailwind ConfigurationLocation: tailwind.config.mjs:1

package.json

Purpose: Project metadata and dependenciesKey Scripts:

npm run dev - Start development server
npm run build - Build for production
npm run preview - Preview production build

Dependencies:

astro (^5.7.10)
@astrojs/tailwind (^6.0.2)
tailwindcss (^3.4.17)
terser (^5.46.0)

Location: package.json:1

Source Directory (`src/`)

The src/ directory contains all application code:

src/
├── assets/                  # Images and media
│   └── imgProfile.png       # Profile image
├── components/              # Reusable Astro components
│   ├── About.astro          # About section
│   ├── CaseStudyCard.astro  # Case study card component
│   ├── Contact.astro        # Contact section
│   ├── Footer.astro         # Site footer
│   ├── Hero.astro           # Hero section
│   ├── LanguageSelector.astro  # Language switcher
│   ├── Navbar.astro         # Navigation bar
│   ├── Projects.astro       # Projects/case studies section
│   ├── Skills.astro         # Skills section
│   └── ThemeToggle.astro    # Dark mode toggle
├── i18n/                    # Internationalization
│   └── utils.ts             # Translation utilities
├── layouts/                 # Page layouts
│   └── Layout.astro         # Main layout wrapper
├── pages/                   # File-based routing
│   ├── index.astro          # Root redirect
│   ├── es/                  # Spanish pages
│   │   └── index.astro      # Spanish homepage
│   └── en/                  # English pages
│       └── index.astro      # English homepage
└── env.d.ts                # TypeScript environment types

Assets Directory

src/assets

directory

Stores images and media files that are processed by Astro’s asset pipeline

Contents:

imgProfile.png - Profile picture used in Hero and About sections

Benefits:

Automatic image optimization
Type-safe imports
Responsive image generation

Usage:

---
import profileImg from '@/assets/imgProfile.png';
---

<img src={profileImg.src} alt="Profile" />

Components Directory

src/components

directory

Reusable Astro components for building the UI

Each component is a self-contained .astro file:

About.astro

About section with education, experience, and certifications

CaseStudyCard.astro

Reusable card component for displaying case studies

Contact.astro

Contact section with email, LinkedIn, and GitHub links

Footer.astro

Site footer with copyright and attribution

Hero.astro

Hero section with greeting, name, role, and CTAs

LanguageSelector.astro

Language switcher for toggling between Spanish and English

Navbar.astro

Navigation bar with section links

Projects.astro

Projects and case studies showcase section

Skills.astro

Technical and soft skills display

ThemeToggle.astro

Dark/light mode toggle button

Component Organization:

All components use the i18n utilities for translations (src/i18n/utils.ts:251)
Components are composed in page files (src/pages/*/index.astro)
Styling uses Tailwind utility classes (tailwind.config.mjs:1)

i18n Directory

src/i18n

directory

Internationalization utilities and translations

Files:

utils.ts

Purpose: Translation system implementationExports:

languages - Language configuration
defaultLang - Default language (‘es’)
translations - All translation strings
TranslationKey - TypeScript type for keys
getLangFromUrl() - Extract language from URL
useTranslations() - Create translation function
getLocalizedPath() - Generate localized URLs

Reference: See i18n UtilitiesLocation: src/i18n/utils.ts:1

Translation Structure: All UI text is stored in the translations object with keys organized by section:

// Navigation
'nav.home', 'nav.about', 'nav.projects', 'nav.skills', 'nav.contact'

// Hero
'hero.greeting', 'hero.name', 'hero.role', 'hero.bio', 'hero.cta'

// Other sections...
'about.*', 'edu.*', 'exp.*', 'case*.*', 'skills.*', 'contact.*', 'footer.*'

Layouts Directory

src/layouts

directory

Page layout components that wrap page content

Files:

Layout.astro

Purpose: Main layout wrapper for all pagesResponsibilities:

HTML document structure
<head> metadata and SEO
Global styles and scripts
Dark mode initialization
Common page wrapper

Usage:

---
import Layout from '@/layouts/Layout.astro';
---

<Layout title="Kevin Palma - Azure Cloud Engineer">
  <!-- Page content -->
</Layout>

Location: src/layouts/Layout.astro:1

Pages Directory

src/pages

directory

File-based routing - each file becomes a route

Structure:

src/pages/
├── index.astro      # Root (/) - redirects to /es/
├── es/
│   └── index.astro  # Spanish homepage (/es/)
└── en/
    └── index.astro  # English homepage (/en/)

Routing Behavior:

/           →  Redirects to /es/
/es/        →  src/pages/es/index.astro
/en/        →  src/pages/en/index.astro
/es/#about  →  /es/ with #about anchor
/en/#about  →  /en/ with #about anchor

Page Composition: Each language version:

Imports the main Layout
Imports section components (Hero, About, Projects, etc.)
Detects language using getLangFromUrl(Astro.url)
Passes language to components for translation

Public Directory

public

directory

Static assets served as-is (not processed by build tools)

public/
├── cv/                      # Resume/CV files
│   ├── en/
│   │   └── CV Kevin Maximiliano Palma Romero - Azure Cloud Engineer 2026.pdf
│   └── es/
│       └── CV Kevin Maximiliano Palma Romero - Azure Cloud Engineer 2026.pdf
└── favicon.svg              # Site favicon

Usage: Files in public/ are accessible at the root URL:

<!-- Favicon -->
<link rel="icon" href="/favicon.svg" />

<!-- CV Download Links -->
<a href="/cv/en/CV Kevin Maximiliano Palma Romero - Azure Cloud Engineer 2026.pdf" download>
  Download CV
</a>

Files in public/ are not processed or optimized. Use src/assets/ for images that need optimization.

Build Output (`dist/`)

dist

directory

Generated directory containing the production build (not committed to Git)

Created by: npm run build Contents:

Optimized HTML files
Minified CSS and JavaScript
Processed assets
Static files from public/

Deployment: The dist/ directory is ready for deployment to:

Vercel
Netlify
Cloudflare Pages
Any static hosting service

File Naming Conventions

.astro files

Astro components and pages
Example: Hero.astro, index.astro

.ts files

TypeScript utilities and types
Example: utils.ts, env.d.ts

.mjs files

ES Module JavaScript config files
Example: astro.config.mjs, tailwind.config.mjs

.json files

JSON configuration and data
Example: package.json

Import Aliases

The project may use path aliases for cleaner imports:

// Instead of:
import Layout from '../../layouts/Layout.astro';
import { useTranslations } from '../../i18n/utils';

// Use aliases:
import Layout from '@/layouts/Layout.astro';
import { useTranslations } from '@/i18n/utils';

Check tsconfig.json (if present) for path alias configuration.

Development Workflow

Local Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Visit:
# http://localhost:4321/es/  (Spanish)
# http://localhost:4321/en/  (English)

Production Build

# Build optimized site
npm run build

# Preview locally
npm run preview

# Deploy dist/ directory

Best Practices

Component OrganizationKeep components focused and reusable. Each component should have a single responsibility.

Asset Management

Use src/assets/ for images that need optimization
Use public/ for files that should be served as-is (PDFs, favicons)
Name files descriptively (e.g., imgProfile.png vs img1.png)

i18n Consistency

Keep all translations in src/i18n/utils.ts
Use translation keys consistently across components
Follow the established naming pattern: section.item

Git IgnoreNever commit:

node_modules/
dist/
.env files
Build artifacts

These should be in .gitignore.

Adding New Pages

To add a new page to the site:

Create page files in both language directories:

src/pages/es/new-page.astro
src/pages/en/new-page.astro

Add translations to src/i18n/utils.ts:

'newpage.title': 'New Page Title',
'newpage.content': 'Page content...',

Update navigation in Navbar.astro if needed
Test both languages:
- /es/new-page
- /en/new-page

Utilities

Configuration

​Project Structure

​Overview

​Root Directory

​Configuration Files

​Source Directory (src/)

​Assets Directory

​Components Directory

About.astro

CaseStudyCard.astro

Contact.astro

Footer.astro

Hero.astro

LanguageSelector.astro

Navbar.astro

Projects.astro

Skills.astro

ThemeToggle.astro

​i18n Directory

​Layouts Directory

​Pages Directory

​Public Directory

​Build Output (dist/)

​File Naming Conventions

.astro files

.ts files

.mjs files

.json files

​Import Aliases

​Development Workflow

​Local Development

​Production Build

​Best Practices

​Adding New Pages

​Related Documentation

Build docs developers (and LLMs) love

Project Structure

Overview

Root Directory

Configuration Files

Source Directory (`src/`)

Assets Directory

Components Directory

i18n Directory

Layouts Directory

Pages Directory

Public Directory

Build Output (`dist/`)

File Naming Conventions

Import Aliases

Development Workflow

Local Development

Production Build

Best Practices

Adding New Pages

Related Documentation