Project Structure

Understanding the project structure is essential for both developers and content editors. This guide provides a complete overview of how files are organized and where to find what you need.

High-Level Overview

The FiNAN website follows a standard Astro project structure:

finan-website/
├── src/                    # Source code (where you work)
├── public/                 # Static assets (served as-is)
├── dist/                   # Build output (generated, don't edit)
├── node_modules/           # Dependencies (auto-installed)
├── Configuration files     # Astro, TypeScript, ESLint, etc.
└── Documentation files     # README, CLAUDE.md, etc.

Source Directory (`src/`)

This is where all your work happens. The src/ directory contains all source code, components, pages, and data.

Complete Source Structure

src/
├── assets/              # Optimized images and media
│   └── images/
│       ├── committee/   # Committee member photos (by country)
│       ├── events/      # Event banners and images
│       └── gallery/     # Photo gallery images
├── components/          # Reusable UI components (25 components)
│   ├── Navbar.astro
│   ├── Footer.astro
│   ├── Committee.astro
│   ├── FAQAccordion.astro
│   └── ... (21 more)
├── data/                # Type-safe data configurations
│   ├── representation/  # Regional representation data
│   │   ├── committee/   # Committee member data
│   │   ├── partnership/ # Partnership data
│   │   └── publication/ # Publication data
│   ├── pages/           # Page-specific data
│   │   └── faq/         # FAQ data
│   ├── events/          # Event-specific data
│   ├── siteConfig.ts    # Site metadata and SEO
│   ├── ctaBannerConfig.ts
│   ├── heroConfig.ts
│   ├── pillarsConfig.ts
│   ├── registrationSectionConfig.ts
│   └── statisticsConfig.ts
├── layouts/             # Page layout templates
│   ├── BaseLayout.astro # Base HTML structure
│   └── MainLayout.astro # Main site layout
├── pages/               # File-based routing (18 pages total)
│   ├── representation/  # Nordic country pages (8 pages)
│   │   ├── denmark.astro
│   │   ├── faroe-islands.astro
│   │   ├── finland.astro
│   │   ├── greenland.astro
│   │   ├── iceland.astro
│   │   ├── kingdom-denmark.astro
│   │   ├── norway.astro
│   │   └── sweden.astro
│   ├── index.astro                         # Home page
│   ├── about.astro                         # About page
│   ├── membership.astro                    # Membership page
│   ├── faq.astro                           # FAQ page
│   ├── guides-resources.astro              # Guides & Resources
│   ├── contact.astro                       # Contact page
│   ├── terms-agreement.astro               # Terms page
│   ├── triennial-gathering-2026.astro      # Event page
│   ├── sitemap.xml.ts                      # XML sitemap
│   └── 404.astro                           # 404 error page
├── scripts/             # Client-side JavaScript
│   └── countdown.js     # Event countdown timer
├── styles/              # Global CSS styles
│   └── global.css       # Global styles and Tailwind imports
└── lib/                 # Utility functions and integrations
    └── ghost.ts         # Ghost CMS client configuration

Public Directory (`public/`)

Static assets that are served as-is without optimization:

public/
├── flags/               # Country flag SVG files
│   ├── denmark.svg
│   ├── finland.svg
│   ├── norway.svg
│   └── ... (more flags)
├── icons/               # UI icons and graphics
│   └── various icon files
├── images/              # General static images
└── favicon.svg          # Website favicon

Important: Files in public/ are not optimized by Astro. Use src/assets/ for images that need optimization.

Key Directories Explained

Components (`src/components/`)

What it is: Reusable UI building blocks used throughout the website.

Who uses it: Primarily developers, but editors may need to reference component names.

All 25 Components:

Navbar.astro - Main navigation bar
Footer.astro - Site footer
TopBanner.astro - Top announcement banner
PageHeader.astro - Page header component

Hero & Headers

HeroHeader.astro - Landing page hero section
EventHeaderSection.astro - Event page hero with countdown

Representation & Contact

NordicRepresentation.astro - All Nordic countries overview
Committee.astro - Committee members display
RepresentationContactSection.astro - Contact information for regional pages

Content Display

Statistics.astro - Organization statistics
Pillars.astro - Organizational pillars
OurAdvocacy.astro - Original advocacy section
HowWeHelp.astro - Updated advocacy display
Partners.astro - Partner organizations
Partnership.astro - Partnership details
PublicationCard.astro - Publication display

Interactive Components

FAQAccordion.astro - FAQ with collapsible answers
EventSched.astro - Event schedule accordion
CTABanner.astro - Call-to-action banners
RegistrationSection.astro - Registration forms

Blog & News

Blog.astro - Main blog section
BlogRepresentation.astro - Regional blog for country pages

SEO & Data

StructuredData.astro - Structured data for search engines

Example component usage:

---
import Committee from '../components/Committee.astro';
import { finlandCommittee } from '../data/representation/committee';
---

<Committee committee={finlandCommittee} country="Finland" />

Data (`src/data/`)

What it is: Type-safe configuration files that store all website content and settings.

Who uses it: Both developers and content editors (especially committee and FAQ files).

Committee Data (`src/data/representation/committee/`)

Most important for editors!

committee/
├── types.ts                  # TypeScript type definitions
├── index.ts                  # Exports all committees
├── finlandCommittee.ts       # Finland committee members
├── swedenCommittee.ts        # Sweden committee members
├── norwayCommittee.ts        # Norway committee members
├── denmarkCommittee.ts       # Denmark committee members
├── icelandCommittee.ts       # Iceland committee members
├── faroeIslandsCommittee.ts  # Faroe Islands committee members
└── greenlandCommittee.ts     # Greenland committee members

Example structure (finlandCommittee.ts):

// Import images
import johnDoeImage from '@/assets/images/committee/finland/john-doe.jpg';
import janeSmithImage from '@/assets/images/committee/finland/jane-smith.jpg';

import type { CommitteeMember } from './types';

// Export committee data
export const finlandCommittee = [
  {
    name: 'John Doe',
    role: 'Country Representative',
    email: 'john.doe@example.com',
    phone: '+358 12 345 6789',
    image: johnDoeImage,
  },
  {
    name: 'Jane Smith',
    role: 'Vice Representative',
    email: 'jane.smith@example.com',
    image: janeSmithImage,
  },
] as const satisfies readonly CommitteeMember[];

FAQ Data (`src/data/pages/faq/`)

Important for editors!

faq/
└── faqData.ts   # All FAQ questions and answers

Example structure:

export const faqData = {
  general: [
    {
      question: 'What is FiNAN?',
      answer: 'FiNAN is a professional non-profit organization...',
    },
  ],
  membership: [
    {
      question: 'How do I become a member?',
      answer: 'You can become a member by...',
    },
  ],
  // More categories...
};

Other Data Files

siteConfig.ts - Site metadata, SEO settings, social links
ctaBannerConfig.ts - Call-to-action banner configurations
heroConfig.ts - Hero section configuration
pillarsConfig.ts - Organizational pillars data
registrationSectionConfig.ts - Registration form config
statisticsConfig.ts - Organization statistics

Pages (`src/pages/`)

What it is: File-based routing where each .astro file becomes a page on the website.

Who uses it: Developers for creating pages, editors for updating page content.

File-to-URL Mapping:

File Path	URL
`index.astro`	`/` (home page)
`about.astro`	`/about`
`membership.astro`	`/membership`
`faq.astro`	`/faq`
`contact.astro`	`/contact`
`representation/finland.astro`	`/representation/finland`
`representation/sweden.astro`	`/representation/sweden`

Main Pages (10):

Home page (index.astro)
About (about.astro)
Membership (membership.astro)
FAQ (faq.astro)
Guides & Resources (guides-resources.astro)
Contact (contact.astro)
Terms (terms-agreement.astro)
Event (triennial-gathering-2026.astro)
Sitemap (sitemap.xml.ts)
404 error page (404.astro)

Representation Pages (8):

Denmark
Faroe Islands
Finland (includes Åland)
Greenland
Iceland
Kingdom of Denmark (collective)
Norway
Sweden

Assets (`src/assets/`)

What it is: Images and media that are automatically optimized by Astro during build.

Who uses it: Both developers and content editors.

When to use src/assets/ vs public/:

Use `src/assets/` for:	Use `public/` for:
Committee photos	Flag SVGs
Event banners	Icons
Gallery images	Favicon
Any JPG/PNG photos	Static images that shouldn’t change

Committee Images (`src/assets/images/committee/`)

Most important for editors!

committee/
├── finland/
│   ├── john-doe.jpg
│   ├── jane-smith.jpg
│   └── ...
├── sweden/
│   ├── member-one.jpg
│   └── ...
├── norway/
│   └── ...
├── denmark/
│   └── ...
└── ... (more countries)

File naming rules:

✅ Use lowercase letters: john-doe.jpg
✅ Use hyphens for spaces: jane-smith.jpg
❌ Don’t use spaces: John Doe.jpg
❌ Don’t use underscores: john_doe.jpg
❌ Don’t use capital letters: JohnDoe.jpg

Layouts (`src/layouts/`)

What it is: Reusable page templates that provide consistent structure.

Who uses it: Primarily developers.

Layout files:

BaseLayout.astro - Base HTML structure with <head> and metadata
MainLayout.astro - Main site layout with navigation and footer

Example usage:

---
import MainLayout from '../layouts/MainLayout.astro';
---

<MainLayout title="About FiNAN">
  <h1>About Us</h1>
  <p>Content goes here...</p>
</MainLayout>

Configuration Files (Root Directory)

These files configure various tools and build processes:

File	Purpose	Who Edits
`astro.config.mjs`	Astro framework configuration	Developers
`package.json`	Project dependencies and scripts	Developers
`tsconfig.json`	TypeScript configuration	Developers
`tailwind.config.js`	Tailwind CSS configuration	Developers
`eslint.config.js`	ESLint code quality rules	Developers
`.prettierrc`	Prettier code formatting	Developers
`security.config.js`	Security headers configuration	Developers
`.gitignore`	Files to exclude from Git	Developers
`.env`	Environment variables (not committed)	Developers

Content editors: You typically don’t need to edit these files.

Important File Patterns

Type-Safe Data Pattern

All data files follow this pattern:

// 1. Import dependencies
import type { SomeType } from './types';
import someImage from '@/assets/images/some-image.jpg';

// 2. Export the data
export const someData = [
  {
    property: 'value',
    image: someImage,
  },
] as const satisfies readonly SomeType[];

Key elements:

Type imports for safety
Image imports with @/assets/ alias
export const to make data available
as const satisfies for type checking

Component Props Pattern

Components accept typed props:

---
interface Props {
  title: string;
  description?: string; // Optional with ?
}

const { title, description } = Astro.props;
---

<h1>{title}</h1>
{description && <p>{description}</p>}

Quick Reference by Role

For Content Editors

Files you’ll work with most:

Committee data - src/data/representation/committee/[country]Committee.ts
Committee photos - src/assets/images/committee/[country]/
FAQ data - src/data/pages/faq/faqData.ts
Event data - src/data/events/
Page content - src/pages/[page-name].astro

Files you won’t edit:

Configuration files (.mjs, .json, .js)
Component files (unless guided by a developer)
Layout files
Build output (dist/)

For Developers

Files you’ll work with:

Components - src/components/ (all 25 components)
Pages - src/pages/ (18 pages)
Data configurations - src/data/ (all data files)
Layouts - src/layouts/
Styles - src/styles/
Configuration - Root config files

Important patterns to follow:

Use TypeScript for type safety
Follow the as const satisfies pattern for data
Use Tailwind CSS for styling
Keep components small and focused
Maintain consistent file naming

Path Aliases

The project uses path aliases for cleaner imports:

Alias	Resolves to
`@/`	`src/`
`@/components/`	`src/components/`
`@/data/`	`src/data/`
`@/assets/`	`src/assets/`
`@/layouts/`	`src/layouts/`

Example:

// Instead of: import img from '../../../assets/images/photo.jpg'
// Use: import img from '@/assets/images/photo.jpg'

Build Output (`dist/`)

What it is: The compiled, production-ready website (generated by npm run build).

Who uses it: Deployment systems (automatically generated, never edit manually).

Contents:

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

Next Steps

Now that you understand the project structure:

Developers: Read Architecture Overview
Content Editors: Read Committee Management
Everyone: Explore the Component API Reference

Common Questions

Q: Where do I put a new committee member photo?
A: In src/assets/images/committee/[country]/ with kebab-case naming.

Q: Where do I edit FAQ questions?
A: In src/data/pages/faq/faqData.ts.

Q: Where are the page files?
A: In src/pages/ - each .astro file becomes a URL.

Q: What’s the difference between src/assets/ and public/?
A: src/assets/ images are optimized; public/ files are served as-is.

Q: Can I delete the node_modules/ folder?
A: Yes, but you’ll need to run npm install to reinstall dependencies.

Q: What is dist/?
A: The build output - don’t edit it directly, it’s auto-generated.