Base template for transversal projects in the AI Engineering Career Program — 4Geeks Academy.
Estas instrucciones tambien estan disponibles en espanol.
This repository is the starter template for transversal projects. You will work on real company scenarios (Brasaland, TrackFlow, Nexova), building deliverables that map to course milestones (Web, Programming, Backend, Telemetry, RAG, Agents, Workflows, Real-time).
- Create a template from this repository.
- Replace the placeholder
CONTEXT.mdwith your assigned company context. - Use
skills/and the directory-levelREADME.mdfiles as working guidance.
- Use this repository as a template and create your own project repo.
- Clone your repository (or open it in Codespaces).
- Replace
CONTEXT.mdwith the full context for your assigned company. - Read this folder guide and open the
README.mdof the folder you are working in. - Start implementing in the right folder — do not dump everything in the root.
- Document what you add: each new app, service, agent, or pipeline gets a subfolder + README.
You are building one company across many milestones and projects. Each top-level folder has a single responsibility — like a real engineering team repo.
| Layer | Folders | What lives here |
|---|---|---|
| Company context | CONTEXT.md |
Domain facts, field names, constraints for your assigned company |
| User-facing | uis/, services/ |
Frontends and backends users (or operators) interact with |
| Data | data/ |
Raw files, pipelines, processed datasets, evaluation sets |
| AI | agents/, skills/, mcps/ |
Agents, reusable agent capabilities, MCP tool servers |
| Automation | workflows/ |
n8n flows and cross-system orchestration |
| Reuse | packages/, shared/ |
Shared types, SDKs, schemas, templates |
| Operations | infra/, scripts/, internal/ |
Docker, deploy configs, one-off scripts, internal CLIs |
| Documentation | docs/ |
Architecture, decisions, conventions for the whole repo |
Rule of thumb: if it has a UI → uis/. If it exposes an API or runs in the background → services/. If it moves or transforms data → data/. If an AI model does the work → agents/ (+ skills/ or mcps/ as needed).
💡 This repository currently provides a base folder structure and documentation skeleton only. It does not include runnable apps or global scripts yet.
CONTEXT.mdis a placeholder and must be replaced with your assigned company context.- There is no root
AGENTS.mdyet.- Shared package metadata exists in
packages/shared/package.json(@repo/shared-types), but no workspace runner is configured at root.
Read the linked README.md inside each folder before you start coding there.
| Path | Purpose | What you do here |
|---|---|---|
CONTEXT.md |
Single source of truth for your company (Brasaland, TrackFlow, or Nexova) | First step: copy your assigned company briefing here so every app, agent, and prompt uses the same domain |
docker-compose.yml |
Local dev orchestration for the whole stack | Keep at repo root — wires services/, databases, and other containers from one place |
README.md / README.es.md |
This guide | Orientation — you are here |
Purpose: All frontend applications — anything a human sees and clicks.
Put here:
- Public website (
website/) - Internal admin / backoffice (
backoffice/) - Customer portals, loyalty apps, Streamlit/Gradio tools, dashboards with a UI
Examples: corporate landing page, operations backoffice, loyalty portal, telemetry dashboard UI
→ See uis/README.md
Purpose: One centralized FastAPI backend for the whole company — a single entry point that keeps complexity low as the project grows.
Put here:
- One main FastAPI app (e.g.
api/) with routers/modules per domain (locations, menus, sales, telemetry, etc.) - Background workers only when they truly need to run separately from the API
Recommendation: avoid splitting into many microservices early. Add endpoints to the same FastAPI app; extract a worker only when necessary.
Examples: /locations, /menus, /sales/reports, webhook handlers, scheduled jobs
→ See services/README.md
Purpose: Everything data-related, from raw files to production-ready tables.
| Subfolder | Purpose | What you do here |
|---|---|---|
data/raw/ |
Untouched source data | Store dumps, exports, sample CSVs/JSON — document origin and PII rules |
data/pipelines/ |
ETL/ELT jobs | Write ingestion, cleaning, and transformation scripts |
data/process/ |
Clean / intermediate outputs | Save artifacts produced by pipelines (features, aggregates, clean tables) |
data/eval/ |
Quality measurement | Golden sets, RAG/agent eval datasets, experiment metrics |
Flow: raw → pipelines → process → consumed by services/, uis/, or agents/. Use eval to prove quality.
Purpose: Autonomous or semi-autonomous AI assistants for the company.
Put here:
- One subfolder per agent (e.g.
support-agent/,onboarding-agent/) - Agent config, prompts, tools wiring, tests
- Start from
agents/_template/when creating a new agent
Examples: customer support bot, employee onboarding copilot, training assistant
→ See agents/README.md
Purpose: Packaged instructions + scripts that agents (or you in Cursor) reuse across the repo.
Put here:
- Skills for data analysis, code review, scraping, research, etc.
- Each skill = a folder with
SKILL.md, optional scripts and resources
Example included: skills/data-analysis/ (pandas cleaning script + metrics reference)
→ See skills/README.md
Purpose: Bridge AI models to your systems — databases, APIs, GitHub, custom tools.
Put here:
- One subfolder per MCP server (e.g.
database-mcp/,github-mcp/) - Tool definitions, resources, and server config
When to use: when an agent needs live access to data or actions your codebase alone cannot provide
→ See mcps/README.md
Purpose: Connect systems without writing full apps — scheduled jobs, webhooks, notifications.
Put here:
- n8n workflow exports, Make/Zapier configs, or orchestration docs
- Flows that link
services/,data/pipelines/, andagents/
Examples: new-order → Slack alert, nightly ETL trigger, lead → CRM sync
→ See workflows/README.md
Purpose: Versionable code reused by multiple apps, agents, or pipelines.
Put here:
- Shared TypeScript types (
packages/shared/→@repo/shared-types) - UI component libraries, API clients, analytics SDKs
Rule: if uis/ and services/ both need the same interface → extract it here
→ See packages/README.md
Purpose: Resources that are not a full package — schemas, templates, static assets, short docs.
Put here:
- JSON schemas, email templates, OpenAPI specs, design tokens
- Anything reused but too small or non-code for
packages/
→ See shared/README.md
Purpose: Architecture and decisions that span the whole company project.
Put here:
- System architecture diagrams, ADRs, security/observability guides
- Conventions not tied to one app or agent
→ See docs/README.md
Purpose: How the company project runs in Docker, cloud, or CI.
Put here:
- Dockerfiles, Terraform, K8s manifests, Nginx configs, CI/CD pipelines
Keep at repo root: docker-compose.yml — orchestrates local dev for services/, databases, and other containers from one place.
→ See infra/README.md
Purpose: Small, repeatable automation — not full apps.
Put here:
- Setup scripts, seed data generators, lint wrappers, one-off migrations
- Document each script: what it does, args, and how to run it
Difference from internal/: scripts are usually single files; internal/ tools are structured projects with their own deps and tests.
→ See scripts/README.md
Purpose: Robust utilities for the engineering team.
Put here:
- CLIs, packaged migration tools, prompt evaluators
- Tools with their own
package.json, tests, and install steps
→ See internal/README.md
Quick decision guide:
Does it have buttons and screens? → uis/
Does it run on a server / API / queue? → services/
Is it raw or transformed data? → data/raw/ or data/process/
Does it move data between systems? → data/pipelines/
Do you measure AI/pipeline quality? → data/eval/
Is it an AI assistant with a goal? → agents/
Is it a reusable AI capability/instruction?→ skills/
Does AI need to call external tools/APIs? → mcps/
Is it n8n / scheduled automation? → workflows/
Will 2+ folders import the same code? → packages/
Is it a schema/template/asset, not a lib? → shared/
Is it architecture or team-wide docs? → docs/
Is it docker-compose for local dev? → repo root
Is it Docker / deploy / cloud config? → infra/
Is it a one-off script? → scripts/
Is it a CLI tool with its own package? → internal/
ai-engineering-company-project-monorepo/
├── README.md / README.es.md # This guide
├── CONTEXT.md # ← Replace with your company briefing
├── docker-compose.yml # ← Local dev orchestration (repo root)
├── uis/ # Frontends (website, backoffice, dashboards)
├── services/ # Centralized FastAPI company API
├── data/
│ ├── raw/ # Source datasets
│ ├── pipelines/ # ETL/ELT jobs
│ ├── process/ # Clean / intermediate outputs
│ └── eval/ # Evaluation sets and metrics
├── agents/ # AI agents (+ _template/ starter)
├── skills/ # Reusable agent skills
├── mcps/ # MCP servers for tool access
├── workflows/ # n8n and automation flows
├── packages/ # Shared libraries (@repo/shared-types, …)
├── shared/ # Schemas, templates, loose assets
├── docs/ # Architecture and cross-cutting docs
├── infra/ # Docker, Terraform, deployment
├── scripts/ # Helper scripts
└── internal/ # Internal CLIs and dev tools
This template was built as part of the 4Geeks Academy AI Engineering Career Program by @marcogonzalo and @alezanchezr and many other contributors. Find out more about our AI Engineering Course, and other courses.
You can find other templates and resources like this at the 4Geeks Academy GitHub page.
This template is maintained by 4Geeks Academy for the AI Engineering track. For exclusive use in the programme.